Zenn
🌐

【Shopify.dev和訳】Apps/Online store/Extensions/Framework

2021/09/11に公開
Shopify
#
apps
tech

この記事について

この記事は、Apps/Online store/Theme app extensions/Frameworkの記事を和訳したものです。

記事内で使用する画像は、公式ドキュメント内の画像を引用して使用させていただいております。

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

https://apps.shopify.com/shopify-application-314?locale=ja&from=daniel

Shopify アプリである、「らくらく日本語フォント設定｜リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

https://apps.shopify.com/font-picker-1?locale=ja&from=daniel

テーマアプリ拡張フレームワーク

このガイドでは、アプリを使用してオンラインストアのテーマを拡張するためのフレームワークについて説明します。

ファイル構造

テーマアプリ拡張機能とは、app blocks、app embed blocks、assets、snippets の bundle のことです。

テーマアプリ拡張機能を作成すると、Shopify は次のtheme-app-extensionディレクトリとサブディレクトリをアプリに追加します。

テーマアプリ拡張ファイルの構造
└── theme-app-extension
    ├── assets
    │   ├── image.jpg
    │   ├── icon.svg
    │   ├── app-block.js
    │   ├── app-block.css
    │   ├── app-embed-block.js
    │   └── app-embed-block.css
    ├── blocks
    │   ├── app-block.liquid
    │   └── app-embed-block.liquid
    ├── snippets
    │   ├── app-block-snippet.liquid
    │   └── app-embed-block-snippet.liquid
サブディレクトリ 説明
blocks app blockとapp embed blocksの Liquid ファイルが含まれています。
assets テーマに挿入される CSS、JavaScript、およびその他の静的アプリコンテンツが含まれています。

アプリは、javascriptとstylesheetのスキーマ属性を使用するか、asset_urlとasset_image_urlの LiquidURL フィルターからアセットを読み込むことができます。
snippets テーマアプリ拡張機能の Liquid のsnippetファイルが含まれています。これは、他の app blocks や app embed blocks で参照できるコードのビットです。

App blocks

ページにインラインコンテンツを挿入するアプリは、app blocks を使用してテーマを拡張します。販売者は、互換性のあるテーマセクションに app blocks を追加することも、セクションレベルで追加されるラッピングされた app blocks として追加することもできます。スキーマのtargetをsectionに設定して、app block を作成します。

デフォルトでは、アプリのインストール後、テーマには app blocks は含まれません。マーチャントは、テーマエディターのアプリセクションから、アプリブロックをテーマに追加する必要があります。

次の種類のアプリには app blocks を使用します。

  • 商品レビューアプリや星評価アプリなど、動的なソースを自動的にポイントするアプリ。
  • 販売者がページ上で再配置したいアプリ。
  • 幅がページの全幅になるアプリ。

テーマが app blocks を導入するには、次のものが必要です。

テーマが app blocks をサポートしているかどうかを確認できます。

app block コードの例

app blockの例
<span style="color: {{ block.settings.colour }}">
App blocks let you build powerful integrations with online store themes!
</span>

{{ "shopify-app-logo.png" | asset_url | img_tag }}

{% render "app_snippet" %}
{% schema %}
  {
    "name": "Hello World",
    "target": "section",
    "stylesheet": "app.css",
    "javascript": "app.js",
    "settings": [
        { "label": "Color", "id": "color", "type": "color", "default": "#000000" }
    ]
  }
{% endschema %}

テーマ内の app blocks の例

以下はセクションに追加された app block の例です。

An example of an app block added to a section. The section is beside a product image and is for a product star ratings app block.

次はラッピングされた app block の例です。

An example of an app block added as a section and wrapped to span the full width of the page. The section is below product details and is for a customer review comments app block.

app blocks のメリット

app blocks は柔軟で、マーチャントはテーマエディターを使用して、セクションレベルで app blocks を追加や、削除、並べ替えをして簡単にカスタマイズできます。

app block は、autofill resource settingsを使用して、動的ソースを自動的にポイントし、コンテンツがその親セクションと同期していることを確認できます。たとえば、商品ページの app block は、動的ソースをポイントして、ページに表示されるさまざまな商品のデータを表示できます。

App embed blocks

UI コンポーネントがないアプリ、またはフローティング要素やオーバーレイ要素を追加するアプリは、app embed blocks を使用してテーマを拡張します。Shopify は、HTML の</ head>および</ body>の終了タグの前に app embed blocks をレンダリングして挿入します。スキーマのtargetをheadまたはbodyに設定して、app embed block を作成します。

デフォルトでは、app embed blocks は、アプリのインストール後には非アクティブ化されていますので、マーチャントは、テーマの設定 > アプリの埋め込みから、テーマエディターで app embed blocks をアクティブ化する必要があります。ただし、アプリは、app embed block を自動的にアクティブ化するために、インストール後にdeep linkをマーチャントに提供できます。

次の種類のアプリには、app embed blocks を使用します。

  • チャットバブルアプリや商品画像バッジアプリなどのような、ページにフローティングコンポーネントまたはオーバーレイコンポーネントを提供するアプリ。
  • SEO メタタグ、アナリティクス、またはトラッキングピクセルを追加するアプリ。

app embed blocks は、セクションや JSON テンプレートに依存しないため、ビンテージテーマと Online Store2.0 テーマでサポートされています。ただし、app embed blocks は動的ソースにポイントことができません。これらのブロックは、レンダリングされたページのグローバル Liquid スコープにのみアクセスできるためです。

App embed block コードの例

app embed blockの例
<div style="position: fixed; bottom: 0; right: 0">
    {{ "kitten.jpg" | asset_url | img_tag }}
</div>
{% schema %}
  {
    "name": "App Embed",
    "target": "body",
    "settings": []
  }
{% endschema %}

テーマ内の app embed block の例

An example of an app embed block injected into a theme's closing HTML body tag. The app provides a floating element on the page and is for a chat bubble app embed block

app embed blocks のメリット

app embed blocks は、ビンテージおよびオンラインストア 2.0 のテーマでサポートされています。これは、2 つのインストールパスを維持する必要なく、すべてのマーチャントがアプリを使用できることを意味します。1 つはビンテージテーマ用で、もう 1 つはオンラインストア 2.0 テーマ用です。

インストール後、マーチャントはテーマコードエディターを使用して app embed block の設定を構成し、よりカスタマイズされた体験を実現できます。

app embed blocks を使用すると、特定のページにのみスクリプトをロードできます。これは、ScriptTag REST Admin APIまたはGraphQL Admin APIリソースでは不可能です。特定のページにスクリプトを読み込むと、必要なページのみにスクリプトが制限されるため、アプリのパフォーマンスへの影響が最小限に抑えられます。

Schema

app blocks と app embed blocks のスキーマはテーマセクションスキーマに似ていますが、次の属性も含まれています。

属性 説明 必須(required?)
name アプリブロックまたはアプリ埋め込みブロックのテーマエディターのタイトル。 はい
target ブロックが配置されている場所。有効なバリューは、section、head、およびbodyです。

app blocks のバリューはsectionです。app embed blocks のバリューは、headとbodyです。		 はい
javascript assetsサブディレクトリからロードする JavaScript ファイル。

ブロックがページに存在する場合は、ページの<head>セクションに<script async>タグを追加することで、このファイルを自動的にロードできます。		 いいえ
stylesheet assetsサブディレクトリからロードする CSS ファイル。

ブロックがページに存在する場合は、ページの<head>セクションに<link rel = "stylesheet">タグを追加することで、このファイルを自動的にロードできます。		 いいえ
templates ブロックがレンダリングされているテンプレート。設定されていない場合、Shopify はデフォルトでサポートされているすべてのテンプレートになります。

有効なバリューはproduct、collection、article、とblog。		 いいえ
class テーマセクションクラスと同様に、ラッピングタグ要素に含まれる追加の CSS クラス。

テーマアプリの拡張機能には、常にshopify-blockクラスが含まれます。		 いいえ
tag 設定されている場合、タグはブロックの出力をラップします。設定されていない場合、出力はdivでラップされます。 いいえ

推奨事項

テーマアプリの拡張機能を構築するための次の推奨事項を確認してください。

Autofill

autofillは、マーチャントが app block をセクションに追加すると、動的ソースに自動的に設定されるアプリブロック設定です。

app blocks には、セクションと同様に、settingsスキーマオブジェクトに設定を含めることができます。リソースを参照する設定に追加のautofill属性を与えることができます。autofillは、マーチャントが app block をセクションに追加すると、Shopify が設定値を自動的に決定することを示します。

autofill設定値は、次の動的ソースのいずれかに設定されます。

  • 同じタイプの親セクションのリソース設定を指し示す動的リソース。
  • テンプレートのグローバルリソースを指し示す動的リソース。

Autofill の例

featured product セクションには、productタイプの設定があります。これにより、販売者は、featured product として表示する商品を選択できます。autofillが設定されたproductの設定を持つ app block は、featured product を自動的に使用します。

次の例では、block.settings.productはセクションのproductの設定を使用します。

Autofillの例
{{ block.settings.product.handle }}

{% schema %}
{
  ...
       "settings": [
         {
           "type": "product",
           "id": "product",
           "label": "Product",
           "autofill": true
         }
       ],
     ...
}
{% endschema %}

ディープリンクにより簡素化されたインストールフロー

インストール後、アプリはディープリンクで販売者にプロンプ ​​ トを表示できます。ディープリンクをクリックすると、テーマエディターで app embed blocks がアクティブになり、マーチャントは保存して公開する前にプレビューと調整を行うことができます。ディープリンクを使用すると、アプリのインストールフローが簡素化されます。これは、マーチャントがテーマエディターに移動し、ブロックを見つけて操作する必要がないためです。代わりに、あなたのアプリはマーチャントのために仕事をします。マーチャントはブロックをプレビューできるため、ストアフロントに何を含めるかをコントロールできます。

サンプル URL

アプリは、クエリパラメータを入力して、マーチャントを次の URL にリダイレクトする必要があります。

App embed blockのURL
https://{shop}.myshopify.com/admin/themes/current/editor?context=apps&template=${template}&activateAppId={uuid}/{handle}

URL のクエリパラメータ

クエリパラメータ 説明
{shop} マーチャントのショップの名前

ShopのREST Admin API リソースまたはGraphQLAdminAPI オブジェクトから{shop}値を取得します。
context アプリがアクティブ化されているコンテキスト。バリューはappsです。
{template} ブロックがレンダリングされるテンプレート。設定されていない場合、Shopify はデフォルトでインデックステンプレートになります。

有効なバリューは、product、collection、article、およびblogです。
{uuid} テーマアプリの拡張機能。

Shopify CLI のshopify extension infoコマンドを使用して{uuid}バリューを取得します。 Shopify CLI を使用してテーマアプリ拡張機能を構築する方法の詳細については、テーマアプリ拡張機能の使用開始を参照してください。
{handle} ブロックの Liquid ファイルのファイルの名前。

たとえば、Liquid ファイルがtheme-app-extension/blocks/app-embed.liquidにある場合、{handle}はapp-embedです。

app embed block のコンテキストでこの Liquid ファイルを表示するには、テーマアプリ拡張機能の開始サンプルコードを参照してください。

ライフサイクル管理とバージョン管理

パートナーダッシュボードを使用して、テーマアプリ拡張機能のライフサイクルを管理します。

Shopify CLI の拡張プッシュコマンドは、アプリの更新を開発ストアのドラフトバージョンにプッシュします。オンラインストアに公開する前に、サンドボックス環境でテーマアプリの拡張機能をテストできます。準備ができたら、アプリを同時に使用するオンラインストアにアプリをデプロイできます。

たとえば、次のことを確認します。

  • フローティングコンポーネントの app embed blocks は、ページのコンテンツを隠すことなく適切に配置されます。
  • テーマエディターを使用して、app embed blocks をアクティブ化および非アクティブ化し、それらの設定を構成できます。
  • テーマエディターを使用して、アプリブロックを追加、削除、再配置し、それらの設定を構成できます。
  • アプリのオンボーディング手順などのアプリのドキュメントは、明確、正確、完全です。効果的なヘルプドキュメントの作成の詳細については、Shopify Polaris のヘルプドキュメントを参照してください。

パフォーマンス

assets/フォルダー内のすべてのファイルは、Shopify's CDNから自動的に提供されるため、高速で信頼性の高いアセット配信が可能です。javascriptおよびstylesheetスキーマ属性を使用するか、asset_urlおよびasset_img_urlの Liquid URL フィルターを使用して、アセットを参照します。

app embed blocks の場合、特定のページにのみスクリプトをロードする機能を利用します。

テーマエディターの互換性

アプリがテーマエディター環境で動作することを確認する必要があります。必要に応じて、テーマエディターを検出するようにアプリを設定して、その環境で動作するようにアプリを調整できます。

施行および提案された制限

Shopify は、拡張機能のドラフトバージョンにプッシュするか、バージョンを作成するときに、テーマアプリの拡張機能を検証します。アプリのコンテンツが強制制限を超えると、テーマアプリの拡張機能は検証に失敗し、更新されません。

次の表に、テーマアプリの拡張機能に適用される制限と推奨される制限を示します。

アプリのコンテンツ 制限 強制または提案
テーマアプリの拡張子のすべてのファイル 10MB 強制
ブロックの数 10 強制
全てのブロックにわたる Liquid のサイズ 100KB 強制
スキーマによって直接参照される CSS（圧縮）のサイズ 100KB 提案
スキーマによって直接参照される JS（圧縮）のサイズ 10KB 提案

次のステップ

  • テーマアプリ拡張機能の構築を開始します。

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

https://apps.shopify.com/shopify-application-314?locale=ja&from=daniel

Shopify アプリである、「らくらく日本語フォント設定｜リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

https://apps.shopify.com/font-picker-1?locale=ja&from=daniel

Discussion

ログインするとコメントできます