ストアフロント API¶

ストアフロント API は、ストアフロントでカスタムのギフトカードの選択と購入のフローを構築するための JavaScript インターフェース（window.GiftHeroAPI）を提供します。

ストアフロント API の設定

API を有効にする¶

左のナビゲーションで For developers を開きます。
Enable storefront API にチェックを入れて保存します。

ギフトカードの商品ページにアプリが生成するギフトカード画面はオフになり、代わりに window.GiftHeroAPI が読み込まれます。画面はご自身で構築します。

この API はギフトカードの残高を読み取りません。購入者の選択内容を収集し、ギフトカードをカートに追加するだけです。

ヘッドレスストアフロント

ヘッドレスストアフロントでは、ヘッドレスモードと Enable storefront API の両方がオンのときに、API が読み込まれます。ヘッドレス連携をご覧ください。

初期化¶

API は非同期で読み込まれます。準備が整うと、Gift Card Hero は window 上でイベントを発火します。メソッドを呼び出す前に、このイベントを待ち受けてください。

window.addEventListener('gift.hero:initalized', function () {
  const api = window.GiftHeroAPI;
  // API is ready to use
});

イベント名は initalized と綴られています

イベント名には綴りの誤りがあります: gift.hero:initalized（"i" が1つ足りません）。書かれている通りに正確に使用してください。このイベントは、document ではなく window で発火し、Gift Card Hero のストアフロントのスクリプトが読み込まれた後に発火します。スクリプトがページにない場合、またはストアフロント API がオフの場合は、イベントは発火しません。

API が開始すると、最初のバリアント（または ?variant= URL パラメーターのバリアント）と最初の画像を選択します。

メソッド¶

addToCart(quantity?, skipValidation?)¶

ギフトカードのデータを検証し、設定されたギフトカードを Shopify の /cart/add.js を使ってカートに追加します。

try {
  const result = await window.GiftHeroAPI.addToCart(1);
  // result: { status: 200, data: { ... } }
} catch (e) {
  // e: { status: 400, data: { errors: ['...'] } } when validation fails
}

パラメーター	型	初期値	説明
`quantity`	number	1	追加するギフトカードの数
`skipValidation`	boolean	false	`validate()` がエラーを報告しても、カードを追加します

戻り値: Shopify のカートのレスポンス（{ status, data }）を含む Promise。検証が失敗すると、{ status: 400, data: { errors } } で拒否されます。

generatePreview()¶

現在までに設定されたデータを使い、受取人に表示されるギフトカードのプレビューを開きます。

window.GiftHeroAPI.generatePreview();

getImages()¶

ギフトカードで使用できる画像 URL の配列を返します。独自のデザイン、選択された組み込みデザイン、有効になっている場合は商品画像が含まれます。

const images = window.GiftHeroAPI.getImages();
// ['https://cdn.shopify.com/...', 'https://cdn.shopify.com/...']

getOptions()¶

利用できる金額を含む、商品のオプションを返します。

const options = window.GiftHeroAPI.getOptions();

getTranslations()¶

ラベルや検証メッセージなど、現在の言語のインターフェースの翻訳を返します。

const translations = window.GiftHeroAPI.getTranslations();

getVariants()¶

商品のバリアントの配列を返します。

const variants = window.GiftHeroAPI.getVariants();

setCardData(cardData)¶

ギフトカードのデータをすべて一度に設定します。

window.GiftHeroAPI.setCardData({
  variantId: 12345678,
  image: 'https://cdn.shopify.com/...',
  message: 'Happy Birthday!',
  from: 'Alice',
  to: 'Bob',
  deliveryDate: new Date('2026-12-25'),
  email: 'recipient@example.com'
});

項目	型	説明
`variantId`	number	選択したバリアントの ID
`image`	string	選択したカード画像の URL
`message`	string	ギフトカードのメッセージ
`from`	string	送信者の名前
`to`	string	受取人の名前（省略可）
`deliveryDate`	`Date`	予約配信日。JavaScript の `Date` オブジェクトとして指定します（省略可）
`email`	string	受取人のメールアドレス（省略可）

API では SMS 配信を利用できないため、電話番号の項目はありません。

個別のセッター¶

メソッド	パラメーター	説明
`setDeliveryDate(date)`	`Date`	予約配信日を設定します。有効な日付オブジェクトでない場合はエラーになります
`setEmail(email)`	string	受取人のメールアドレスを設定します
`setFrom(name)`	string	送信者の名前を設定します
`setTo(name)`	string	受取人の名前を設定します
`setImage(image)`	string	選択したカード画像の URL を設定します
`setMessage(message)`	string	ギフトカードのメッセージを設定します
`setVariant(variantId)`	number or string	選択するバリアントを設定します
`setProperty(name, value)`	string, string	カートの明細に、追加の明細プロパティを追加します

validate()¶

現在のギフトカードのデータを検証し、{ valid, errors } を返します。errors は、翻訳から作成されたメッセージの配列です。

const { valid, errors } = window.GiftHeroAPI.validate();

検証ルール:

受取人のメールアドレスが設定されている場合、配送日、送信者の名前（from）、メッセージが必須です。
配送日が設定されている場合、受取人のメールアドレス、送信者の名前、メッセージが必須です。
メールアドレスも配送日もない場合、必須項目はありません。

setCustomAmount(amount)¶

ストアの通貨で任意の金額を選択します（例: 75 は 75.00）。任意金額がストアで有効になっている場合にのみ動作します。そうでない場合は Custom amount is not enabled をスローします。このメソッドは最小金額と最大金額をチェックしないため、金額はご自身で検証してください。

window.GiftHeroAPI.setCustomAmount(75);

物理ギフトカード¶

物理ギフトカードを販売している場合は、setCardType('physical') で API を切り替えます（setCardType('eGift') で元に戻します）。

メソッド	説明
`setCardType(type)`	`'eGift'` または `'physical'`。`'physical'` を選択すると、最初の物理バリアントと画像が選択されます
`getPhysicalProduct()`	物理ギフトカードの商品
`getPhysicalVariants()`	物理商品のバリアント
`getPhysicalImages()`	物理商品の画像 URL
`setPhysicalVariant(variantId)`	物理バリアントを選択します（物理タイプのみ）
`setPhysicalDeliveryAddress(address)`	配送先の住所を設定します（物理タイプのみ）: `firstName`、`lastName`、`address`、`zipCode`、`city`、`country`、省略可能な `state`
`isPhysicalCard()`	物理タイプが選択されている場合は `true`

uploadCustomDesign(file, options?)¶

購入者自身の画像をアップロードし、その URL を返します。この URL は setImage() に渡せます。

const { url } = await window.GiftHeroAPI.uploadCustomDesign(file);
window.GiftHeroAPI.setImage(url);

ファイルは JPG、PNG、GIF、WebP 形式の画像で、初期設定では最大5 MBです。options.maxSize（バイト）と options.allowedTypes で上限を変更できます。ファイルが拒否された場合、このメソッドはわかりやすいメッセージとともにエラーをスローします。

React との連携例¶

JSFiddle に、完全な React の連携例があります。API の初期化、カスタムのギフトカード選択 UI の構築、カートへの追加の処理を示しています。

JSFiddle で React の例を見る