コンテンツにスキップ

ガチャ画面との接続

このページでは、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 残高表示する場合は必要 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/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 ガチャの一覧ページが表示された
select_content ガチャが選択された
view_item ガチャページが表示された
begin_checkout 「ガチャる」ボタンが押された

商品データ

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

商品パラメータ
id ガチャID
name gacha-{ガチャID}
list_name gachas
brand gacha-{ガチャID}
list_position 表示順
price 価格

自社アプリ側での設定

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': [
      {
        'id': '{ガチャID}',
        'name': 'gacha-{ガチャID}',
        'brand': 'gacha-{ガチャID}'
      }
      // ...
    ],
  });

購入完了画面

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

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


最終更新日: 2021-03-03