使用 Rails 順利嵌入 JS 小工具：逐步指南

建立可嵌入客戶端網站的自訂 JavaScript 小工具是擴展 Ruby on Rails 應用程式範圍的有效方法。無論是聊天框、分析追蹤器或任何其他互動元素，自訂小工具都可以讓您直接向使用者提供功能。讓我們逐步了解建立安全、可嵌入小部件的步驟並介紹最佳實踐。

目錄

 1. 第 1 步：設定
 2. 第 2 步：為客戶端建立嵌入程式碼
 3. 步驟 3：將您的小工具嵌入 Iframe 中（選購）
 4. 第 4 步：設定 Iframe 嵌入的標頭
 5.步驟5：測試小工具
 6. 第 6 步：使用版本化路由和控制器新增版本支援

第 1 步：設定

建立一個新的 Rails 端點：該端點將為您的小部件提供 JavaScript 程式碼。通常，這可能是 WidgetsController 中的一個操作：

# app/controllers/widgets_controller.rb
class WidgetsController 



<p>配置路線：設定路線以使小部件可存取。 <br>
</p>

<pre class="brush:php;toolbar:false"># config/routes.rb
Rails.application.routes.draw do
  get '/widget.js', to: 'widgets#show', as: :widget
end

從控制器提供 JavaScript：在 Rails 中，您可以透過設定適當的內容類型來使用 JavaScript 來回應。

# app/controllers/widgets_controller.rb
class WidgetsController 



<p>為您的小部件編寫 JavaScript 程式碼：小部件腳本通常包含在客戶端頁面上呈現自訂 HTML 元素或 iframe 的邏輯。 <br>
</p>

<pre class="brush:php;toolbar:false">// app/views/widgets/show.js.erb
(function() {
  const widgetDiv = document.createElement('div');
  widgetDiv.id = 'custom-widget';
  widgetDiv.innerHTML = "<p>This is your custom widget content!</p>";
  document.body.appendChild(widgetDiv);
})();

第 2 步：為客戶建立嵌入程式碼

要允許客戶嵌入您的小部件，請提供一個 JavaScript 片段，他們可以將其複製並貼上到 HTML 中：

<!-- Client Embeddable Code -->
<script type="text/javascript">
  (function() {
    const script = document.createElement('script');
    script.src = "https://yourapp.com/widget.js";
    script.async = true;
    document.head.appendChild(script);
  })();
</script>

步驟 3：將您的小部件嵌入到 Iframe 中（可選）

考慮將小部件內容嵌入到 iframe 中，以更好地隔離和控制樣式。這種方法使小部件的樣式和行為與客戶端網站分開。

更新 JavaScript 程式碼以為小工具建立 iframe：

// app/views/widgets/show.js.erb
(function() {
  const iframe = document.createElement('iframe');
  iframe.src = "";
  iframe.style.width = "300px";
  iframe.style.height = "200px";
  document.body.appendChild(iframe);
})();

為小工具內容定義新的路由和視圖：

# config/routes.rb
Rails.application.routes.draw do
  get '/widget_content', to: 'widgets#content', as: :widget_content
end

# app/controllers/widgets_controller.rb
def content
  render layout: false
end

建立小工具內容 HTML：建立要在 iframe 內呈現的視圖

<!-- app/views/widgets/content.html.erb -->
<div>



<h2>
  
  
  Step 4: Setting Headers for Iframe Embedding
</h2>

<p>Configure the appropriate HTTP headers to ensure your widget works securely in an iframe. There are two primary headers to consider:</p>

<p><strong>Remove the X-Frame-Options Header</strong>: The X-Frame-Options header is deprecated but still widely respected by many browsers. To remove it, add the following configuration in an initializer:<br>
</p>

<pre class="brush:php;toolbar:false"># config/initializers/security_headers.rb
Rails.application.config.action_dispatch.default_headers.delete('X-Frame-Options')

設定 Frame-Ancestors 指令：現代且更靈活的方法是將 Content-Security-Policy 與frame-ancestors 指令結合使用，它允許您指定允許嵌入小部件的域一個 iframe。根據您的安全要求，根據需要調整此標頭。

# config/initializers/security_headers.rb
Rails.application.config.action_dispatch.default_headers.merge!({
  'Content-Security-Policy' => "frame-ancestors 'self' https://trusted-domain.com"
})

此配置允許您的應用程式僅透過指定的網域嵌入到 iframe 中。將 https://trusted-domain.com 替換為您信任的實際網域。

第 5 步：測試小工具

設定小部件和標題後，透過將小部件嵌入到各種瀏覽器的測試頁面上來測試小部件，以確保相容性。如果您使用了框架祖先，請確認只有指定的域可以嵌入您的小部件並且小部件如預期顯示。

第 6 步：使用版本化路由和控制器新增版本支持

隨著您的小部件的發展，您可能會引入並非所有客戶都準備好立即採用的新功能或改進。支援小部件的多個版本可確保向後相容性，讓客戶可以按照自己的步調升級，而不會中斷其現有的整合。

使用版本化路由和控制器實現版本支持

定義版本化路由

首先為每個版本的小部件設定單獨的路由。每個版本的命名空間可以讓您的程式碼保持井井有條，並允許您獨立管理不同的版本。

# app/controllers/widgets_controller.rb
class WidgetsController 



<h4>
  
  
  建立版本化控制器
</h4>

<p>對於每個版本，在其命名空間內建立一個控制器。這種分離確保一個版本中的變更不會影響其他版本。 <br>
</p>

<pre class="brush:php;toolbar:false"># config/routes.rb
Rails.application.routes.draw do
  get '/widget.js', to: 'widgets#show', as: :widget
end

# app/controllers/widgets_controller.rb
class WidgetsController 



<h4>
  
  
  建立特定於版本的 JavaScript 和 HTML 視圖
</h4>

<p>每個版本都可以有自己的 JavaScript 和 HTML 文件，讓您自訂每個版本的功能和外觀。 </p>

<p><strong>版本 1 JavaScript：</strong><br>
</p>

<pre class="brush:php;toolbar:false">// app/views/widgets/show.js.erb
(function() {
  const widgetDiv = document.createElement('div');
  widgetDiv.id = 'custom-widget';
  widgetDiv.innerHTML = "<p>This is your custom widget content!</p>";
  document.body.appendChild(widgetDiv);
})();

版本 1 內容：

<!-- Client Embeddable Code -->
<script type="text/javascript">
  (function() {
    const script = document.createElement('script');
    script.src = "https://yourapp.com/widget.js";
    script.async = true;
    document.head.appendChild(script);
  })();
</script>

版本 2 內容：

// app/views/widgets/show.js.erb
(function() {
  const iframe = document.createElement('iframe');
  iframe.src = "";
  iframe.style.width = "300px";
  iframe.style.height = "200px";
  document.body.appendChild(iframe);
})();

最後的想法

為 Rails 應用程式建立可嵌入小部件涉及幾個關鍵注意事項：安全地提供 JavaScript、管理樣式以及正確配置標頭以實現 iframe 相容性。透過執行上述步驟，您將擁有一個小部件，客戶可以輕鬆地將其添加到其站點，從而擴展 Rails 應用程式的可用性。