コンテンツにスキップ

ヘッドレス連携

Gift Card Hero は、Shopify の標準テーマシステムを使わないヘッドレスの Shopify ストアフロントに対応しています。ヘッドレスモードを有効にすると、カスタムのストアフロントに埋め込む連携用のコードスニペットが表示されます。

手順 1: ヘッドレスモードを有効にする

左側のナビゲーションで For developers に移動します。Headless mode カードで Enable headless mode をクリックします。ステータスバッジが Enabled に変わります。保存バーの Save をクリックして保持してください。

ヘッドレスモードを有効にする

手順 2: 連携コードをコピーする

ヘッドレスモードを有効にすると、ページにコードスニペットが表示されます。Copy to clipboard をクリックします。スニペットには、空の <div id="sc-giftcard-builder">、設定ブロック、そして Gift Card Hero のストアフロントスクリプトが含まれています。これをギフトカード商品のページに追加してください。

連携コードのスニペット

手順 3: プレースホルダーを置き換える

コードスニペットには、ご自身のストア固有の情報に置き換える必要があるプレースホルダーの値が含まれています。

プレースホルダー 置き換える内容 例
[MONEY_FORMAT] ストアの金額フォーマット文字列 ${{amount}}
[PRODUCT_ID] ギフトカード商品の Shopify の数値 ID 7654321098765
[MYSHOPIFY_DOMAIN] ストアの .myshopify.com アドレス my-store.myshopify.com
[ADD_TO_CART_CALLBACK] カートへの商品追加を処理する JavaScript 関数 addItemToCart
[LOCALE] 翻訳のロケールコード en

[PRODUCT_ID] は数値で、スニペット内では引用符で囲まれていません。その他は引用符の中に入っています。Gift Card Hero は関数として呼び出すため、'[ADD_TO_CART_CALLBACK]' は引用符ごと、ご自身の関数に置き換えてください(例: addToCart: addItemToCart)。

金額フォーマット

金額フォーマット文字列は、価格の表示方法を決めます。ページには、プレースホルダーの横に、ストア自身の金額フォーマットが例として表示されます。フォーマットコードについては、Shopify の通貨フォーマットのガイドを参照してください。

よく使われるフォーマット:

  • ${{amount}} — 米ドル
  • {{amount}} EUR — ユーロ
  • ${{amount}} CAD — カナダドル

商品 ID

ギフトカード商品の Shopify ID を確認するには、次の手順に従います。

  1. Shopify Admin を開きます
  2. Products に移動します
  3. ギフトカード商品をクリックします
  4. ブラウザーのアドレスバーにある URL を確認します。末尾にある数値が ID です

例えば、URL が https://admin.shopify.com/store/my-store/products/7654321098765 の場合、商品 ID は 7654321098765 です。

カートへの追加のコールバック

[ADD_TO_CART_CALLBACK] のプレースホルダーは、ストアフロントがカートに商品を追加するために使う JavaScript の関数名に置き換えてください。Gift Card Hero は、1つのオブジェクトを渡して呼び出し、Promise が返されることを想定しています。

function addItemToCart({ items, sections }) {
  // items: [{ id: <variant id>, quantity: 1, properties: { ... } }]
  // Add the line to your cart (for example a Storefront API cart) and return a promise.
}

properties には、購入者の選択内容(メッセージ、送信者、受取人、配送日、カードデザインのデータ)が含まれます。ギフトカードが正しく作成されるよう、これらすべてを変更せずにカードの行に渡してください。関数が存在しない場合、カートへの追加は "Add to cart method is not defined in headless mode" というエラーで失敗します。

ロケール

[LOCALE] のプレースホルダーは、Gift Card Hero の画面の言語を設定します。アプリの翻訳で設定済みの言語のコードを、そのまま同じ綴りで使ってください(例: en または fr)。省略すると en になります。

スニペットが設定を取得する仕組み

ページの読み込み時に、ストアフロントスクリプトは https://gifthero.syncu.be/api/configuration/headless にアクセスし、ギフトカードの設定、商品、翻訳を取得します。その際には、[MYSHOPIFY_DOMAIN]、[PRODUCT_ID]、[LOCALE] を使います。ログインは不要です。応答は約1分間キャッシュされ、アプリで設定を保存するとキャッシュが更新されます。

商品 ID が間違っている場合、リクエストは Product id is incorrect で失敗し、何も表示されません。金額フォーマット、商品 ID、またはショップの情報がスニペットから欠けている場合、スクリプトはブラウザーのコンソールにその旨を表示します。

カスタム金額

金額を自由に指定できるギフトカードを販売する場合、金額はアプリで設定した最小額と最大額の範囲内である必要があります。サーバーは、その範囲外の金額を拒否します。Gift Card Hero を通じてチェックアウトが作成されると、サーバーは設定に基づいて注文を組み立て直すため、ブラウザーから価格を変更することはできません。この流れでは、ご自身のカートへの追加関数が呼び出される代わりに、購入者はサーバーから返されたチェックアウトのリンクに移動します。

連携後

スニペットを埋め込み、プレースホルダーを置き換えると、Gift Card Hero がストアフロントにギフトカードの選択画面を表示します。アプリのギフトカードビルダーの代わりにご自身のインターフェースを作る場合は、For developers ページで Enable storefront API もオンにします。すると、ビルダーは表示されなくなり、操作用の Storefront API(window.GiftHeroAPI)が読み込まれます。