Skip to content

ショップ画面との接続

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

画面遷移

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

ショップの画面遷移

Warning

UI Kit は購入確認以降は関与しない点に注意して下さい。UI Kit の役割は、エンドユーザが購入選択したアイテムを自社アプリに引き渡すところまでです。

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

ベースURL

URL

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

パラメータ仕様

パラメータ 必須 説明 値のサンプル
avatarId エンドユーザのアバターID 1234567890
shopId ショップのID。個別のショップを指定する場合は必要。「全てのショップ」を利用する場合は指定不要。 1234567890
money 残高表示する場合は必要 1000
currency 通貨。最大5文字までのUTF8の文字列。残高不足となった場合の誘導ボタンで表示されます。残高表示する場合は必須。 コイン
currencyShort 通貨の略称。1文字のUTF8の文字列。アイテムの価格部に表示されます。 C
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
analyticsDisabled Google アナリティクスを無効にする場合は true を指定します。 true

サンプル

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

https://sdk.avatarplay3d.com/uikit/shop?avatarId=5716311128670208&money=1000&currency=%E3%82%B3%E3%82%A4%E3%83%B3&currencyShort=C&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 を使ってエンドユーザが選択し購入対象となっているアイテムの情報を取得します。

// Go言語での実装例
func ConfirmPurchase(w http.ResponseWriter, r *http.Request) {
    // パラメータ取得
    shopSessionID := r.URL.Query().Get("shopSessionId")
    shopSessionVersion := r.URL.Query().Get("shopSessionVersion")

    // APIエンドポイント
    apiEndpoint := fmt.Sprintf(
        "https://api.avatarplay3d.com/avatar/v1/Shop/Session?key=%s&avatarId=%d&shopSessionId=%s&shopSessionVersion=%s",
        "{APIキー}",
        avatarID,
        shopSessionID,
        shopSessionVersion,
    )

    // APIリクエスト
    res, err := http.Get(apiEndpoint)
    if err != nil {
        http.Error(w, "api failed", http.StatusInternalServerError)
        return
    }

    // レスポンスボディ(JSON)をパース
    type Item struct {
        ItemID       json.Number `json:"itemId"`
        ThumbnailURL string      `json:"thumbnailUrl"`
        Price        int         `json:"price"`
    }
    apiResponse := struct {
        Items []*Item `json:"items"`
    }{}
    if err := json.NewDecoder(res.Body).Decode(&apiResponse); err != nil {
        http.Error(w, "decode failed", http.StatusInternalServerError)
        return
    }

    // ...
}

アイテムID、サムネイル画像URL、価格を取得し、購入確認画面に表示します。アイテムIDと価格は、ユーザと紐付けてサーバ側に一時的に保存しておきます。

Warning

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

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

購入確認画面で、選択中アイテムを解除するUIを実装可能です。また、backUrl に指定したURLを戻せば、アイテムの選択と試着を続きから行えます。

購入処理を実装する

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

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

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

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

// 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")

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

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

行動分析

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

Info

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

イベント

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

商品データ

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

商品パラメータ
id アイテムID
name item-{アイテムID}
list_name 後述
brand shop-{ショップID}
category パーツ名(Hair/Face/Clothes...)
list_position 表示順
price 価格

list_name

ケース
個別ショップの場合 shop-{ショップID}
全てのショップのオススメ shops-featured
全てのショップのパーツ指定 shops-part-{パーツ名}
全てのショップの試着中 shops-selected