着せ替え画面との接続¶
このページでは、UI Kit の着せ替え画面の組み込み方法について説明しています。
着せ替え画面の必要性¶
Avatar Play では、着せ替えアプリを提供しており、着せ替えアプリと接続することで着せ替え機能を利用することも可能です。UI Kit の着せ替え画面が必要となるのは、主に次のようなケースです。
- アバターの着せ替えが自社アプリのコアUXに該当し、かつiOSアプリとして配信するとき(コアUXはアプリ内で完結する必要があるため)
- 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×tamp=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×tamp=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 の利用を解除するページを挟んだ後、親フレームから着せ替えアプリと接続するよう実装してください。backUrl
や completeUrl
を使う場合も同様に、親フレームに戻って次の画面へ遷移するよう実装します。
一部の端末で行動分析する場合¶
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} |