AR Quick LookでのApple Payボタンまたはカスタムアクションの追加

概要

iOS 13.3以降では、Webから開始されたAR体験にApple Payボタンを表示できます。ユーザーはこのボタンを使ってWebサイトで購入を行うことができます。

また、バナー内にテキストを表示し、ユーザーがこのテキストをタップするとWebサイト内でカスタムアクションが起動するようにできます。プレビューしたアイテムをショッピングカートに追加するなどのカスタムアクションが可能です。

さらに、カスタムHTMLを含むAR Quick Lookを提供することで、バナーのグラフィックスを完全にカスタマイズできます。

Apple Payボタンやカスタムテキスト、カスタムグラフィックスをバナーに追加するには、URLパラメータを選択してWebサイトのAR Quick Lookを構成します。最後に、ユーザーがバナーをタップしたことを検出し、それに応じて処理を行うようにします。

Apple Payボタンのスタイルの選択

AR体験に使用するApple Payボタンのスタイルを選択するには、WebサイトのURLにapplePayButtonTypeパラメータを追加します。

https://example.com/biplane.usdz#applePayButtonType=plain

以下に示したボタンの種類の値を使って、ボタンのオプションを選択できます。

カスタムテキストの提供

Apple Payボタンの代わりに、テキストを提供し、下の図のようにAR Quick Lookを使用してカスタムアクションボタンとして表示させることができます。

カスタムテキストを値として、callToAction URLパラメータを追加します。以下のサンプルURLは、「Add to cart」というテキストを使ってバナーをレンダリングします。

https://example.com/biplane.usdz#callToAction=Add%20to%20cart

URLにはスペースを含められないため、必ずカスタムテキストをURLエンコードしてからURLパラメータとして追加してください。Webサイトが複数言語に対応している場合は、カスタムテキストをローカライズしてから、URLパラメータリスト用にURLエンコードします。

アイテムの定義

Apple PayボタンまたはカスタムアクションボタンをAR Quick Lookに追加する場合は、checkoutTitle、checkoutSubtitle、priceのURLパラメータを使って、プレビューされたアイテムの説明を設定します。AR Quick Lookは、タイトルの下に、サブタイトルと価格をカンマで区切って表示します。

サブタイトルと価格が1行で収まらない場合は、AR Quick Lookによってサブタイトルの末尾が省略され、省略記号が表示されます。以下のサンプルURLは、バナーをレンダリングします。

https://example.com/biplane.usdz#applePayButtonType=buy&checkoutTitle=Biplane%20Toy&checkoutSubtitle=Rustic%20finish%20with%20rotating%20propeller&price=$15

Webサイトが複数言語に対応している場合は、アイテムのタイトル、サブタイトル、価格をローカライズしてから、URLパラメータリスト用にURLエンコードします。

カスタムバナーの表示

バナーのグラフィックスを完全にコントロールするには、custom URLパラメータを使ってカスタムHTMLファイルを提供します。以下のサンプルURLは、comingSoonBannerという名前のカスタムファイルからバナーをレンダリングします。

https://example.com/biplane.usdz#custom=https://example.com/customBanners/comingSoonBanner.html

このサンプルURLは、下の画像のようにAR体験で表示されます。

custom URLパラメータを使う場合、値は絶対URLでなければなりません。AR Quick Lookのセキュリティ基準を満たすため、サーバは必ずHTTPSでHTMLリソースを送信するようにしてください。

カスタムバナーの高さの定義

カスタムバナーを表示する場合、customHeight URLパラメータを使ってバナーの高さを設定できます。

small、medium、またはlargeの値を提供して、バナーの高さを81ポイント、121ポイント、または161ポイントに設定します。たとえば、以下のように設定します。

https://example.com/biplane.usdz#custom=https://example.com/my-custom-page.html&customHeight=large

バナーの幅は、バナーが表示されるデバイスのサイズと向きに合わせて自動的に調整されます。カスタムバナーの幅は最大で450ポイントです。customHeight URLパラメータを省略すると、AR Quick Lookはデフォルト値のsmallを使用します。

タップの検出

ユーザーがApple Payボタンまたはカスタムアクションボタンをタップすると、3Dアセットを参照するコードの<a>要素に、WebKitがDOMメッセージを送信します。

<a id="ar-link" rel="ar" href="https://example.com/cool-model.usdz#applePayButtonType=pay....etc">  <img src="poster.jpg"></a>

タップの通知を受け取れるように、アンカーでmessageイベントのJavaScriptリスナーを定義します。

const linkElement = document.getElementById("ar-link");
linkElement.addEventListener("message", function (event) { ... }, false);

WebKitがリスナーを呼び出したら、dataプロパティをチェックします。値が_apple_ar_quicklook_button_tappedであれば、ユーザーがAR Quick Lookでバナーをタップしたことがわかります。

const linkElement = document.getElementById("ar-link");
linkElement.addEventListener("message", function (event) {   
    if (event.data == "_apple_ar_quicklook_button_tapped") {
        // handle the user tap.   
    }
}, false);

messageイベントは、通常のDOM処理ルールに従います。特定アンカーのリスナーを追加する代わりに、ドキュメントルートですべてのARリンクのリスナーを追加し、event.targetを使って、ユーザーがどのアンカーを呼び出したのか判断することもできます。

タップに対する処理

イベントリスナーで、ユーザーのタップに対してWebサイトが実行するアクションを定義します。ユーザーがカスタムアクションボタンをタップした場合は、バナーのテキストおよびカスタムアクションに基づいて、プレビューされたアイテムをショッピングカートに追加したり、ユーザーを支払い手続きページに案内します。

バナーにApple Payボタンを表示している場合は、Apple Pay JS API（英語）を使ってApple Payプロンプトを表示します。

バナーにMessages for Businessボタンを表示している場合は、企業のカスタムMessages for Business URLを使ってユーザーを「メッセージ」にリダイレクトします。詳しくは、「URLによるチャットの開始（英語）」を参照してください。