ショップ画面との接続¶

このページでは、UI Kit のショップ画面の組み込み方法について説明しています。

Info

本機能はβ版のため、将来仕様が変更する可能性があります。

画面遷移¶

UI Kit のショップ画面が提供するのは、アイテムの選択と試着のUIです。「購入確認」ボタンが押された後は自社アプリに戻り、購入確認から購入処理を行います。

ショップの画面遷移

購入確認から購入処理が自社アプリ側の責務となるため、エンドユーザとの最終的な合意、残高チェックなどを自社アプリ側で実装する必要があります。

必要な権限¶

ガチャを利用するユーザは、ItemGrant パーミッションを持っていることが前提となります。ゲストユーザ作成時、または着せ替えアプリ接続時に指定する scope パラメータに、ItemGrant パーミッションを含めるようにしてください。

接続用エンドポイントを構成する¶

サーバサイドで接続用エンドポイントを構成し、エンドユーザを誘導します。まずベースURLを作成し、最後に署名を付けたURLへエンドユーザをリダイレクトします。

ベースURL¶

URL¶

https://sdk.avatarplay3d.com/uikit/shop

パラメータ仕様¶

パラメータ	必須	説明	値のサンプル
avatarId	○	エンドユーザのアバターID	1234567890
shopId		ショップのID。個別のショップを指定する場合は必要。「全てのショップ」を利用する場合は未指定にします。	1234567890
currencyId		通貨ID。通貨設定から確認できます。「全てのショップ」を利用する場合に指定します。	1234567890
money	○	所持残高。double 型。	1000
chargeUrl	○	残高不足の場合に誘導する自社アプリのエンドポイント	https://example.com/charge.html
purchaseUrl	○	購入確認用の自社アプリのエンドポイント	https://example.com/purchase_confirm.html
backUrl		「戻る」ボタンが押された場合の戻り先URL。指定した場合、UI Kit ショップ画面の下部に「戻る」ボタンが表示されます。	https://example.com/home
styleUrl		独自スタイルシートを読み込む場合はそのURL	https://example.com/custom.css
timestamp	○	UNIXタイムスタンプ	1584519473

サンプル¶

完成したベースURLは次のようになります。

https://sdk.avatarplay3d.com/uikit/shop?avatarId=5716311128670208&money=1000&shopId=1234567890&chargeUrl=https%3A%2F%2Fexample.com%2Fcharge.html&purchaseUrl=https%3A%2F%2Fexample.com%2Fpurchase_confirm.html&timestamp=1584925992

署名¶

着せ替え画面と同様に、ベースURLの末尾に署名を付加します。

セッション¶

UI Kit のショップ画面へ無事遷移すると、UI Kit 側でセッションIDが生成されます。購入確認画面では、このセッションIDを用いて選択しているアイテムと関連情報を取得します。

購入確認画面を実装する¶

購入確認画面は自社アプリ側で実装する必要があります。 purchaseUrl で指定したエンドポイントに、以下パラメータが付加されたURLにエンドユーザが来訪します。

パラメータ	説明	値のサンプル
shopSessionId	ショップのセッションID	abcdefg...
shopSessionVersion	セッションのバージョン	3
backUrl	ショップ画面に戻す場合のURL	https://sdk.avatarplay3d.com/uikit/shops.html?a=1234567890

自社アプリではこのパラメータを取得し、Shop API を使ってエンドユーザが選択し購入対象となっているアイテムの情報を取得します。アイテムID、サムネイル画像URL、価格、通貨IDを取得し、購入確認画面に表示します。アイテムIDと価格は、ユーザと紐付けてサーバ側に一時的に保存しておきます。

Warning

価格の値はユーザから送信された値ではなく、Shop API から取得した値を利用して下さい。Shop API が返す値は、コンソールの「ショップ」で登録した値です。

購入確認画面のカスタマイズ¶

購入確認画面で、選択中アイテムを解除するUIを実装可能です。購入前に利用規約への同意を取る必要がある場合はここの画面で同意を取ります。また、backUrl に指定したURLを戻せば、アイテムの選択と試着を続きから行えます。

購入処理を実装する¶

購入確認を完了したら、自社アプリでの購入処理とアイテム付与を実行します。アイテム付与はアイテム付与APIを利用します。

// Go言語でのアイテム付与APIリクエスト実装例

// APIエンドポイント
apiEndpoint := fmt.Sprintf("https://api.avatarplay3d.com/v1/Avatar/%d/Items?key=%s", {アバターID}, "{APIキー}")

// リクエストボディ
params := url.Values{}
params.Add("itemId", itemId) // 購入するアイテムIDを追加
params.Add("failIfOwnedItemExists", "true")
params.Add("shopSessionId", shopSessionId)

// APIリクエスト
req, err := http.NewRequest("POST", apiEndpoint, strings.NewReader(params.Encode()))
if err != nil {
    http.Error(w, "new request failed", http.StatusInternalServerError)
    return
}

// URLエンコードを指定する
req.Header.Add("content-type", "application/x-www-form-urlencoded")

// JWTを設定。JWTの生成方法は RESTful API の概要ページを参照。
req.Header.Add("Authorization", "Bearer "+jwt)

res, err := http.DefaultClient.Do(req)
if err != nil || res.StatusCode != 200 {
    // rollback
    http.Error(w, "api failed", http.StatusInternalServerError)
    return
}

ショップの購入では、failIfOwnedItemExists を true に指定します。これにより、購入確認画面で確認した全てのアイテムが、全て付与されるか、全て失敗(全て付与されない)かのどちらかとなり、購入確認画面からの一貫性が保たれます。

shopSessionId を指定するとセッション情報がクリアされます。指定しなかった場合、所持金額などが古い状態のセッションが再利用されてしまう可能性があるため、必ず指定するようにしてください。

1度に購入できるアイテム点数

アイテム付与APIに指定できるアイテム数は最大10点までとなっています。UI Kit のショップ画面も、1度に購入できるアイテム数が最大10点となるようUI設計されているため、ユーザが11点以上のアイテムを選択した状態で購入確認画面に遷移してくることはありません。将来的に1度に購入できるアイテム点数の制約は変更される可能性があります。

行動分析¶

自社アプリと Google アナリティクスを統合した場合、イベントが自社アプリの Google アナリティクスへ送信されます。パラメータは Google アナリティクスのeコマースの仕様に準拠しているため、自社アプリ側も同様に設定することで、UI Kit を跨ったeコマーストランザクションを測定できます。

Info

UI Kit における行動分析の概要はプライバシーと行動分析のページを参照して下さい。

UI Kit が送信する値¶

イベント¶

イベント	説明
view_item_list	アイテムが表示された
add_to_cart	未所持のアイテムが選択された
remove_from_cart	未所持のアイテムが選択解除された
begin_checkout	「購入確認」ボタンが押された

商品データ¶

view_item_list で送信される商品データは次のようになります。

商品パラメータ	値
item_id	item-{アイテムID}
item_name	item-{アイテムID}
item_list_id	後述
item_list_name	後述
item_brand	shop-{ショップID}
item_category	パーツ名(Hair/Face/Clothes...)
index	表示順
price	価格
currency	通貨設定で指定した通貨名
quantity	1が設定されます

item_list_id / item_list_name に設定される値¶

ケース	item_list_id の値	item_list_name の値
個別ショップの場合	shop-{ショップID}	ショップ {ショップ名}
全てのショップのオススメ	shops-{通貨ID}-featured	全てのショップ({通貨名}) オススメ
全てのショップのパーツ指定	shops-{通貨ID}-part-{パーツ名}	全てのショップ({通貨名}) {パーツ名}
全てのショップの試着中	shops-{通貨ID}-selected	全てのショップ({通貨名}) 選択中

自社アプリ側での設定¶

gtag.js を使用した場合の自社アプリ側のタグ実装例を示します。

共通¶

サーバサイドでアバターIDをSHA256暗号化し、Google アナリティクスのユーザIDに指定します。

<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id={プロパティID}"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());

  gtag('config', '{自社の Google アナリティクスのプロパティID}', {
    'user_id': '{SHA256暗号化したアバターID}'
  });
</script>

購入確認画面¶

購入確認画面に表示したアイテム情報を、 checkout_progress イベントで送信します。item_name はコンソールでアイテム名を設定している場合にのみ設定します。

  gtag('event', 'checkout_progress', {
    'items': [
      {
        'item_id': 'item-{アイテムID}',
        'item_name': '{アイテム名}'
      }
      // ...
    ],
  });

購入完了画面¶

purchase イベントを使って購入完了を送信します。 transaction_id には、自社が発行したトランザクションIDを指定します。item_name はコンソールでアイテム名を設定している場合にのみ設定します。

  gtag('event', 'purchase', {
    'transaction_id': '{トランザクションID}',
    'items': [
      {
        'item_id': 'item-{アイテムID}',
        'item_name': '{アイテム名}'
      }
      // ...
    ],
  });

最終更新日: 2021-07-12