コンテンツにスキップ

着せ替え画面との接続

このページでは、UI Kit の着せ替え画面の組み込み方法について説明しています。

着せ替え画面

着せ替え画面の必要性

Avatar Play では、着せ替えアプリを提供しており、着せ替えアプリと接続することで着せ替え機能を利用することも可能です。UI Kit の着せ替え画面が必要となるのは、主に次のようなケースです。

  1. アバターの着せ替えが自社アプリのコアUXに該当し、かつiOSアプリとして配信するとき(コアUXはアプリ内で完結する必要があるため)
  2. Avatar Play のインストールやサインインが必須となる点が、UX上好ましくないとき

Info

UI Kit の着せ替え画面を利用する場合も、着せ替えアプリとの接続は必須です。

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

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

Info

着せ替えアプリとの接続と異なり、リンク元のレギュレーションはありません。自由な文言、画像から UI Kit 着せ替え画面へリンクを張ることができます。

ベースURL

URL

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

パラメータ仕様

パラメータ 必須 説明 値のサンプル
avatarId エンドユーザのアバターID 1234567890
connectUrl 着せ替えアプリと接続するためのURL。詳細は後述。 https://example.com/connect
completeUrl 「保存」ボタン(着せ替え完了ボタン)が押された場合の戻り先URL。指定しなかった場合、UI Kit の着せ替え画面で「保存しました」と表示されます。 https://example.com/home
backUrl 「戻る」ボタンが押された場合の戻り先URL。指定した場合、UI Kit 着せ替え画面の下部に「戻る」ボタンが表示されます。着せ替え画面からアプリへ戻るために、completeUrl または backUrl のどちらかは指定するようにしてください。 https://example.com/home
styleUrl 独自スタイルシートを読み込む場合はそのURL https://example.com/custom.css
timestamp UNIXタイムスタンプ 1584519473

Info

connectUrl で指定するエンドポイントの実装は、一旦後回しにして進めることも可能です。着せ替え画面上部に警告が表示されますが、接続を完了すると消えます。

サンプル

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

https://sdk.avatarplay3d.com/uikit/fitting_room?avatarId=1234567890&completeUrl=https%3A%2F%2Fexample.com%2Fhome&connectUrl=https%3A%2F%2Fexample.com%2Fconnect&timestamp=1584519638

署名

次に、ベースURLに署名を付加します。

事前準備

自社アプリが利用する署名キーの生成を、一度だけ行う必要があります。コンソールのアプリ一覧から対象アプリの「アプリ設定」へ進み、「UI Kit を有効化する」ボタンを押します。

UI Kit を有効化すると次の画面で16進数表記(HEXエンコード)された署名キーが表示されます。署名キーは署名に用いる際の秘密鍵ですので、安全な経路で自社アプリが参照できる位置(通常は自社サーバ)に保存します。

Warning

コンソールでの署名キーの表示は一度だけです。署名キーを失念しないよう注意して下さい。

署名の生成

前述のベースURLと署名キーを使って、HMAC SHA256のアルゴリズムで署名を生成し、16進数表記に変換した文字列を利用します。

key, err := hex.DecodeString("{16進数表記の署名キー}"))
if err != nil {
    log.Fatal("failed to decode sign key")
    return err
}

mac := hmac.New(sha256.New, key)
if _, err := mac.Write([]byte(baseURL)); err != nil {
    log.Fatal("failed to sign")
    return
}
sign := hex.EncodeToString(mac.Sum(nil))
// 16進数表記の署名キーをバイト配列に戻す
var keyBytes = new List<byte>();
for (int i = 0; i < "{16進数表記の署名キー}".Length / 2; i++)
{
    keyBytes.Add(Convert.ToByte("{16進数表記の署名キー}".Substring(i*2, 2), 16));
}
var key = keyBytes.ToArray();

// 署名
var signBytes = new HMACSHA256(key).ComputeHash(System.Text.Encoding.UTF8.GetBytes(baseURL));
var sign = BitConverter.ToString(signBytes).ToLower().Replace("-", "");

ベースURLに署名を付加する

ベースURLの末尾に、sign というパラメータ名で、署名を追加します。最終的なエンドポイントURLのサンプルは次のとおりです。

https://sdk.avatarplay3d.com/uikit/fitting_room?avatarId=1234567890&completeUrl=https%3A%2F%2Fexample.com%2Fhome&connectUrl=https%3A%2F%2Fexample.com%2Fconnect&timestamp=1584519638&sign=c232ba1ad9f2f68499ba9af4924a6e367f709ead749b92063a174222d07f6642

セキュリティ上の注意点

第三者による不正アクセスを防ぐために、署名キーをサーバサイドに配置し、サーバサイドで署名を生成するようにします。また、ユーザ認証をサーバサイドで行い、ユーザに紐づくアバターIDを、avatarId パラメータに設定するようにします。エンドユーザから送信されるアバターIDを利用しないよう注意してください。これは、ショップ・ガチャにおいても同様です。

着せ替えアプリとの接続

続いて、connectUrl のエンドポイントの実装を行います。こちらは着せ替えアプリとの接続を参照して下さい。

着せ替えアプリがインストール済みのとき

端末に着せ替えアプリがインストールされている場合は、UI Kit の着せ替え画面ではなく着せ替えアプリが自動起動します。着せ替えアプリがインストールされていない場合、UI Kit の着せ替え画面が表示されます。UI Kit 着せ替え画面の動作を確認する際は、端末から着せ替えアプリをアンインストールする必要があります。

アプリ内ブラウザの利用

UI Kit はアプリ内ブラウザで利用できます。その際、以下の Avatar Play のドメインをアプリ内ブラウザで実行するようにしてください。

  • sdk.avatarplay3d.com
  • fit.avatarplay3d.com

iframe 内での利用(β)

着せ替え画面はいくつかの注意点を理解した上で、iframe 内での利用を検討できます。iframe の利用が必要となる主なシーンは、アプリのヘッダー・フッターがウェブの技術で実装されており、着せ替え画面もそのUI/UXを適用したいときです。

Info

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

Warning

本機能は、iOS 14 での ITP の挙動を元に設計されています。ITP の制約は年々強くなる傾向があり、UI Kit の仕様もそれに追従して将来的に変更される可能性があります。iframe の利用は安定性に欠けるため、特別な理由なく利用するのは避けてください。

Info

iframe 内での利用が可能なのは着せ替え画面だけです。ショップ画面・ガチャ画面は iframe 内ではご利用になれません。

iframe に対するブラウザの制約

iframe 内で自社アプリと異なるドメインのウェブページを表示する場合、プライバシーを保護するためのブラウザの各制約を受けることが分かっています。特に iOS と Safari ブラウザにおいては、ITP(Intelligent Tracking Prevention) の影響を強く受けます。

UI Kit 着せ替え画面にユーザのプライバシーを取得するような目的はありませんが、自社アプリへ組み込んで使うという性質上、特に iframe 内においては一部の機能が制約を受けます。

iframe 内で利用する際の注意点

UI Kit 着せ替え画面を iframe 内で利用する際は、以下の点に注意してください。

  • 着せ替えアプリインストール済みの連携済みユーザであっても、着せ替えアプリは起動せず UI Kit 着せ替え画面が表示されます
  • completeUrl など、URLを持つパラメータの値に識別子のような値を付加することはできません
  • 着せ替えアプリへの接続は必ず親フレームで実行する必要があります
  • iOS や Safari では Google アナリティクスによる行動分析はできません

iframe の利用を開始する

iframe の利用を開始する場合、本運用前に Avatar Play 担当者に申し出てください。iframe での利用を最適化するためには DeNA 側でのセットアップ作業が必要です。

Info

iframe 内でのUI/UXを確認するために、事前に iframe 内での表示を試すことは可能です。

実装上の注意点

URLに識別子を含めないようにする

completeUrl など、URLを持つパラメータの値に識別子のような値を含めないようにします。例えば次のようなURLは通常問題にはなりませんが、

https://example.com/

識別子のようなパラメータが付く以下のようなURLは、ITP によってブロックされることがあります。

https://example.com/?sessionid=qwertyuiop

不要なリダイレクトを避ける

パラメータに指定したURLでは、不要なリダイレクトが実行されないようにします。これはCSSなどページに埋め込むアセットのURLも該当します。リダイレクトが必要な場合は、1度親フレームに遷移してから実行するようにします。

適宜親フレームへ戻るようにする

必須パラメータである connectUrl では、iframe の利用を解除するページを挟んだ後、親フレームから着せ替えアプリと接続するよう実装してください。backUrlcompleteUrl を使う場合も同様に、親フレームに戻って次の画面へ遷移するよう実装します。

一部の端末で行動分析する場合

iOS や Safari では Google アナリティクスが動作しませんが、他の端末においては Cookie の SameSite の値を None に変更することで Google アナリティクスを有効化できます。この設定は、コンソールのアプリの設定で変更できます。

行動分析(β)

自社アプリと Google アナリティクスを統合した場合、以下のイベントが自社アプリの Google アナリティクスへ送信されます。行動分析の概要はプライバシーと行動分析のページを参照して下さい。

Info

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

UI Kit が送信する値

イベント

イベント 説明
select_content アイテムをクリックし、試着した
commit 試着を完了し、「保存」ボタンをクリックした
select_content のパラメータ

select_content イベント発生時に送信されるデータは次のようになります。

パラメータ
content_type item
item_id item-{アイテムID}

最終更新日: 2022-01-21