ガチャ画面との接続¶

このページでは、UI Kit のガチャ画面の組み込み方法について説明しています。

Info

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

画面遷移¶

UI Kit のガチャ画面が提供するのは、ガチャページまでです。「ガチャる」ボタンが押された後は自社アプリに戻り、購入確認(ガチャ演出含む)から購入処理を行います。

ガチャの画面遷移

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

必要な権限¶

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

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

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

ベースURL¶

URL¶

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

パラメータ仕様¶

個別のガチャを指定する場合¶

パラメータ	必須	説明	値のサンプル
avatarId	○	ユーザのアバターID	1234567890
gachaId	○	ガチャの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

ガチャの一覧を指定する場合¶

パラメータ	必須	説明	値のサンプル
avatarId	○	ユーザのアバターID	1234567890
currencyId	○	通貨ID。複数指定可。通貨設定から確認できます。	1234567890
money-{currencyId}	○	通貨毎の所持残高。double 型。	1000
chargeUrl-{currencyId}		通貨毎の残高不足の場合に誘導する自社アプリのエンドポイント。未指定の場合は誘導ボタンが非表示となります。	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

通貨毎の所持残高は、money-1234567890=500 のように指定します。

サンプル¶

個別のガチャを指定した場合の、完成したベースURLは次のようになります。

https://sdk.avatarplay3d.com/uikit/gacha?avatarId=5716311128670208&money=1000&gachaId=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にユーザが来訪します。

パラメータ	説明	値のサンプル
gachaSessionId	ガチャのセッションID	abcdefg...

自社アプリではこのパラメータを取得し、Gacha API を使ってユーザが引き当てたアイテムの情報を取得します。引き当てたアイテムIDと価格は、ユーザと紐付けてサーバ側に一時的に保存しておきます。複数の通貨を扱っている場合、通貨IDも同様に保存しておきます。初回無料アイテムの場合、Price の値は必ず 0 となります。

アイテムの引き当てはユーザが「ガチャる」ボタンを押した時点で決定するため、同じセッションIDからは必ず同じアイテムIDが返されます。

Warning

この時点では、引き当てたアイテムの情報がユーザに漏洩しないよう注意してください。

Warning

UI Kit はユーザとの購入契約が自社アプリ側で担保されることを前提としているため、購入確認画面の表示をスキップすることは推奨されません。

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

購入確認画面では、ガチャの演出などを行って購入するボタンを配置します。ユーザは戻るボタンなどで前のガチャページに戻って再操作することはできず、最初からやり直す必要があります。

購入処理を実装する¶

購入確認を完了したら、自社アプリでの購入処理とアイテム付与を実行します。アイテム付与はアイテム付与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("gachaSessionId", gachaSessionId)

// 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
}

gachaSessionId を指定するとセッション情報がクリアされ、初回無料アイテムの場合は初回無料が完了したことが記録されます。指定しなかった場合、所持金額などが古い状態のセッションが再利用されてしまう可能性があることに加え、初回無料の状態が反映されないため必ず指定するようにしてください。

行動分析¶

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

Info

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

UI Kit が送信する値¶

ガチャの場合、商品(item)がガチャに該当します。ショップの場合は商品がアバターアイテムであるため、ショップと異なる点に注意してください。

イベント¶

イベント	説明
view_item_list	ガチャの一覧ページが表示された
view_item	ガチャページが表示された
begin_checkout	「ガチャる」ボタンが押された

商品データ¶

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

商品パラメータ	値
item_id	gacha-{ガチャID}
item_name	ガチャ名
item_list_id	gachas-{ハイフン区切りの通貨ID}
item_list_name	ガチャ一覧
index	表示順
price	価格
currency	通貨設定で指定した通貨名
quantity	1が設定されます

自社アプリ側での設定¶

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 イベントで送信します。

  gtag('event', 'checkout_progress', {
    'items': [
      {
        'item_id': 'gacha-{ガチャID}',
        'item_name': '{ガチャ名}'
      }
      // ...
    ],
  });

購入完了画面¶

purchase イベントを使って購入完了を送信します。 transaction_id には、自社が発行したトランザクションIDを指定します。

  gtag('event', 'purchase', {
    'transaction_id': '{トランザクションID}',
    'items': [
      {
        'item_id': 'gacha-{ガチャID}',
        'item_name': '{ガチャ名}'
      }
      // ...
    ],
  });

最終更新日: 2021-07-14