クイックスタート - 組み込み開発編¶
このページでは、プロフィールを持つ一般的なウェブサイトでの連携実装手順を説明します。
システム要件¶
以下のシステム構成の、コミュニティを持つ一般的なウェブサイトを想定します。
- PC/モバイルに対応したウェブサイト
- プロフィール画像を保存するストレージがある
この場合、着せ替えアプリと接続した後、アバター画像を自社のストレージに保存してプロフィール画像として利用し、ユーザがアバターを変更した際は Webhook でハンドリングして随時アバター画像を更新するこちらの組み合わせが推奨されます。
事前準備¶
コンソールへの招待¶
まず、Avatar Play 担当者よりコンソールへの招待を受ける必要があります。コンソールへサインインし、招待を受理すると次のようにコンソールの各メニューが表示されます。
アプリの登録¶
コンソールから自社のアプリを登録します。左メニューの「アプリ」を選択し、アプリを登録します。アプリは環境毎(開発、本番など)に登録する必要がありますが、ここでは開発用のアプリとして進めます。
アプリ名は必須項目のため、仮でも良いので入力します。「開発用のアプリ」を有効にし、「登録」ボタンを押して新規作成します。「開発用のアプリ」以外の項目は後から変更できます。
アプリが登録されるとアプリIDが発行されます。ここではアプリIDは 5695024129900544 としておきます。
RESTful API の有効化¶
自社アプリがウェブアプリの場合、RESTful API を有効化する必要があります。本クイックスタートでは、簡単のためにJWTの認証実装をスキップして進めます。
Warning
本番のアプリケーションでは、必ずJWT認証を実装してください。
RESTful API の概要に従い、API キーの作成までを完了します。その後、API キーをSHA256で暗号化した文字列を取得します。
# Macでのコマンド例
$ echo -n {API キー} | shasum -a 256
854834d71cfb50b614d34863a601fc22375c0c39b477bbb83e63105f1863280a -
コンソールのアプリの「設定」ページへ遷移し、RESTful API 向けの設定の、「API キーとサービス アカウントの登録」をクリックします。
「API キーとサービス アカウントの登録」画面では、先程のSHA256で暗号化した文字列を「暗号化した API キー」に入力し、「サービス アカウントのメールアドレス」はクイックスタートでは空にしておきます。
「登録」ボタンを押すと、API キーが登録されます。
Echo API へアクセスして、API キーが有効となったことを確認できます。API キーのみでアクセスする場合、ドメイン api-ko.avatarplay3d.com へアクセスします。以下は curl コマンドで API を呼び出した例です。
$ curl "https://api-ko.avatarplay3d.com/v1/Echo?key={API キー}&message=hello"
{"message":"hello"}
{"message":"hello"} が返れば接続に成功しています。
着せ替えアプリとの接続¶
着せ替えサービスを利用するために、着せ替えアプリとの接続を実装します。これは一般的な OAuth に従った実装になります。モバイルウェブから接続した場合、β版の着せ替えアプリ(Avatar Play アプリ)と接続しますが、PCウェブからはウェブ版の Avatar Play と接続する形になりなす。自社アプリ側の実装はPC/モバイルで差異がないため、共通化できます。
自社アプリ側のUI実装¶
自社アプリ側から接続エンドポイントへのリンクを張る必要があります。これはマイページのような場所でも、設定ページでもどこでも構いません。
接続用エンドポイントを構成する¶
着せ替えアプリと接続するためには、接続用エンドポイントを構成してユーザを誘導する必要があります。
パラメータの設定¶
接続用エンドポイントに渡すパラメータを設定していきます。アプリIDは、コンソールより得られた 5695024129900544 を利用します。
リダイレクトURI(redirectUri)¶
ユーザが接続を承認すると、リダイレクトURIへ返ってきます。前のアプリの設定で、「リダイレクトURI」が未登録の場合は登録しておきます。ここでは、http://localhost/callback を設定したものとします。
スコープ(scope)¶
自社アプリに必要な権限をスコープに設定します。ここでは、自社アプリ側でアイテム付与まで行えるようにするために AvatarLoad,ItemGrant を指定します。
タイムスタンプ(requestDate)¶
リクエスト時のUnixタイムスタンプを取得します。直接接続用エンドポイントへは渡しませんが、codeChallenge の生成と、後の Access Token API で利用するため、サーバサイドのキャッシュなどに一時保存しておきます。ここでは 1552893948 としておきます。
codeVerifier¶
codeVerifier 用の乱数を生成し、タイムスタンプ同様一時保存しておきます。ここでは、値を qwertyuiop とします。
codeChallenge¶
codeChallenge を作るには、まずアプリID、レスポンスタイプ(grant_token で固定)、リダイレクトURI、スコープ、タイムスタンプ、API キー、codeVerifier をコロン「:」区切りで連結します。
5695024129900544:grant_token:http://localhost/callback:AvatarLoad,ItemGrant:1552893948:{API キー}:qwertyuiop
これをSHA256でハッシュ化した文字列が codeChallenge です。ここでは、asdfghjkl が得られたものとしておきます。
接続用エンドポイントを完成させる¶
接続用エンドポイント https://fit.avatarplay3d.com/connect に、アプリID、リダイレクトURI、スコープ、codeChallenge を設定して完成です。パラメータ値は、忘れずにURLエンコードします。
https://fit.avatarplay3d.com/connect?appID=5695024129900544&redirectUri=http%3A%2F%2Flocalhost%2Fcallback&scope=AvatarLoad%2CItemGrant&codeChallenge=asdfghjkl
このURLへユーザを誘導します。
リダイレクトURIをハンドリングし、接続を完了する¶
ユーザによって連携が承認されると、リダイレクトURIにユーザが戻ってきます。このとき、リダイレクトURIにパラメータ token が付与されているため、このパラメータの値を取得します。そして Access Token API へリダイレクトURI、スコープ、タイムスタンプ、codeVerifier を指定して呼び出し、接続を完了させます。
$ curl -X POST "https://api-ko.avatarplay3d.com/v1/AccessToken?key={API キー}" \
-d "redirectUri=http%3A%2F%2Flocalhost%2Fcallback&scope=AvatarLoad%2CItemGrant&requestDate=1552893948&codeVerifier=qwertyuiop"
Access Token API の返り値として、アバターIDとアバター画像URLを取得できます。アバターIDは、自社アプリで管理するユーザIDとマッピングし、データベース等に保持しておきます。アバター画像URLは、そのユーザの初期のアバター画像となるため、ダウンロードしてプロフィール画像として保存し、ユーザのプロフィールとして各画面で表示するようにします。
接続完了後の着せ替えアプリの起動¶
連携済みのユーザは、以降は連携用のエンドポイントではなく、起動用のエンドポイントへ誘導します。このエンドポイントから、自社アプリのアバターを着せ替えることができます。
https://fit.avatarplay3d.com/launch?appId=5695024129900544
アバターの変更をハンドリングしてプロフィール画像を更新する¶
ユーザがアバターを変更した際は、着せ替えの通知を Webhook を使ってハンドリングし、該当ユーザのプロフィール画像を更新します。
Webhook の有効化¶
Webhook を有効化するには、コンソールのアプリの設定から、「Webhook を有効化する」ボタンを押します。
署名キーが表示されるので、失念や漏洩しないように保持しておきます。この署名キーは、Webhook が Avatar Play から呼び出されたものであることを認証するために利用します。
アプリの設定から「変更」リンクを押すと、Webhook の「ペイロード受信用URL」を登録できるようになっています。ここに、着せ替え通知を受け取る自社アプリのエンドポイントを設定します。
ペイロード受信用エンドポイントを実装する¶
以降、着せ替えが行われるとペイロード受信用エンドポイントが呼び出されます。ペイロード中に、アバターIDとアバター画像URLが含まれているため、アバター画像をダウンロードし、該当のアバターIDを持つユーザのプロフィール画像を更新します。