アプリ組み込み
このページでは、WebアプリまたはiOS/AndroidアプリにJINS MEME APIを組み込む方法について説明します。
WebアプリにJINS MEME APIを組み込む
認可コードフロー
JINS MEME APIのアクセスにはアクセストークンが必要です。アクセストークンはOAuth 2.0の認可コードフローに基づき取得します。アプリで認可コードフローを利用するには、アプリからサーバへのリクエスト送信と、JINSプラットフォームからアプリへのデータ受信を実行できる必要があります。認可コードフローの概要は以下の通りです。
認可コードフローに伴うステップは、以下のとおりです。
- ユーザーはアプリのログイン操作を実施します。
- アプリからJINSログインの認可URLをブラウザに送信して、ブラウザはログイン画面を開きます。
- ユーザーはログイン認証します。JINSプラットフォームでユーザーの資格情報が検証された後、ユーザーはアプリから要求される権限を付与することに同意します。
- JINSプラットフォームからアプリに、redirect_uriを介してユーザーをリダイレクトします。このとき、認可コードとstateを含むクエリ文字列もアプリに送信されます。
- アプリは認可コードを使ってアクセストークンを要求します。JINSプラットフォームはアプリからのリクエストを検証して、アクセストークンをアプリに返します。
- アプリは取得したアクセストークンを使って、APIを呼び出すことができます。
認可を要求する
ユーザーを認証してアプリに権限を付与するよう要求するには、以下の認可URLに必須のクエリパラメータを付けてユーザーをリダイレクトします。ユーザーをリダイレクトするには、直接リンクを使います。
https://accounts.jins.com/jp/ja/oauth/authorize
必須のクエリパラメータをURLに含める必要があります。
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
| response_type | String | 必須 | “code”固定。この値を指定することにより、JINSプラットフォームから認可コードが返されます。 |
| client_id | String | 必須 | アプリID。JINS MEME DEVELOPERSでプラットフォーム「Web」を設定したアプリを登録した際に払い出されたアプリID。 |
| redirect_uri | String | 必須 | コールバックURL(要URLエンコード)。認証と認可の後にユーザーがリダイレクトされるURLです。JINS MEME DEVELOPERSでアプリケーションに登録したコールバックURLと完全に一致する必要があります。 |
| state | String | 必須 | クロスサイトリクエストフォージェリ防止用の固有な英数字の文字列。アプリ側でランダムに生成する必要があります。 |
| scope | String | 必須 | ユーザーが付与する権限。URLエンコードされた空白文字（%20）で区切って、複数のスコープを指定できます。詳しくは、「スコープ」を参照してください。 |
| service_id | String | 必須 | “meme”固定。 |
| login_hint | String | 任意 | ログインメールアドレス。指定されたメールアドレスがログイン画面のメールアドレスに設定されます。 |
scopeパラメータに指定できるスコープは以下のとおりです。URLエンコードされた空白文字（%20）で区切って、複数のスコープを指定できます。少なくとも1つのスコープを指定する必要があります。
| スコープ | 説明 |
|---|---|
| official | JINS MEME OFFICIAL アプリデータ（15秒・60秒スロット）の参照権限です。 |
認可リクエストの例
以下はクエリパラメータを含む認可URLの例です。
https://accounts.jins.com/jp/ja/oauth/authorize?response_type=code&client_id=123456789012345&redirect_uri=https%3A%2F%2Fexample.com%2Fcb&state=12345abcde&scope=official&service_id=meme&login_hint=test@example.com
認証と認可のプロセス
ユーザーがJINSにログインしていない場合
ユーザーは認証のためJINSログイン画面にリダイレクトされます。ユーザーはメールアドレスとパスワードを使ってJINSにログインする必要があります。ログイン後、認可画面が表示されます。
ユーザーセッションが存在し、JINSにログイン済みである場合
JINSログイン画面の代わりに認可画面が表示されます。
認可コードを取得する
ユーザーの認証と認可が完了すると、HTTPステータスコード302および以下のクエリパラメータを含むコールバックURLが返されます。
| パラメータ | タイプ | 説明 |
|---|---|---|
| code | String | アクセストークンの取得に使用される認可コード。有効期間は10分です。また、認可コードは1回のみ利用可能です。 |
| state | String | 元のリクエストの認可URLに含まれるstateパラメータ。この値が元のリクエストに含まれる値と一致することを、アプリが検証する必要があります。 |
以下は、レスポンスの例です。
HTTP/1.1 302 Found
Location : https://example.com/callback?code=67890fgehi&state=12345abcde
エラーレスポンス
アプリの要求する権限の付与をユーザーが拒否した場合、以下のクエリパラメータを含むコールバックURLが返されます。
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
| error | String | 必須 | “access_denied”固定。認可画面でキャンセルした場合に設定されます。 |
| error_description | String | 必須 | エラー内容。人間が判読できるASCIIエンコードのテキストです。 |
| state | String | 必須 | OAuth 2.0のステート値。認可リクエストにstateパラメータが含まれていた場合は必ず返されます。 |
以下は、エラーレスポンスの例です。
https://example.com/callback?error=access_denied&error_description=The+resource+owner+or+authorization+server+denied+the+request.&state=12345abcde
アプリの要求する権限の付与をユーザーが拒否した場合、アプリ側でエラーを適切に処理する必要があります。
アクセストークンを取得する
アクセストークンを取得するには、認可コードを指定してHTTP POSTリクエストを実行します。取得したアクセストークンで、APIを呼び出すことができます。アクセストークンは、以下のエンドポイントで発行されます。
リクエスト
POST https://apis.jins.com/meme/v1/oauth/token
| リクエストヘッダー | 説明 |
|---|---|
| Content-Type | application/x-www-form-urlencoded |
リクエストボディ
リクエストボディの情報はform-urlencodedフォーマットで記述します。
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
| grant_type | String | 必須 | “authorization_code”固定。 |
| code | String | 必須 | 認可コード。JINSログイン後にコールバックURLに設定された認可コードを指定します。 |
| redirect_uri | String | 必須 | コールバックURL。認可リクエストに指定したコールバックURLを指定します。 |
| client_id | String | 必須 | アプリID。JINS MEME DEVELOPERSでプラットフォーム「Web」を設定したアプリを登録した際に払い出されたアプリID。 |
| client_secret | String | 必須 | アプリSecret。JINS MEME DEVELOPERSでプラットフォーム「Web」を設定したアプリを登録した際に払い出されたアプリSecret。 |
以下はアクセストークンを取得するためのHTTP POSTリクエストの例です。
curl -X POST https://apis.jins.com/meme/v1/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=authorization_code' \
-d 'code=67890fgehi' \
-d 'redirect_uri=https://example.com/cb' \
-d 'client_id=123456789012345' \
-d 'client_secret=67890123456789'
レスポンス
JINSプラットフォームがアプリからのリクエストを検証し、以下の表に示すアクセストークンなどのデータをアプリに返します。
| プロパティ | タイプ | 説明 |
|---|---|---|
| access_token | String | アクセストークン。有効期間は30日です。 |
| refresh_token | String | 新しいアクセストークンを取得するためのトークン。有効期限はありません。 |
| token_type | String | Bearer |
| expires_in | Number | アクセストークンの有効期限が切れるまでの秒数。 |
| scope | String | ユーザーが付与する権限。 |
以下は、JSONレスポンスの例です。
{
"access_token": "47912eb18a59c28550008c725ccba1074934e00c45645a882cfe47611669c298",
"refresh_token": "47912eb18a59c28550008c725ccba1074934e00c45645a882cfe47611669c298",
"token_type": "bearer",
"expires_in": 3600,
"scope": "official"
}
iOS/AndroidアプリにJINS MEME APIを組み込む
前章の「WebアプリにJINS MEME APIを組み込む」で作成したWebアプリ経由でJINS MEME APIを利用します。
iOS/AndroidアプリからJINS MEME APIのアクセスフローは以下のとおりです。
- ユーザーはiOS/AndroidアプリのJINS MEME APIに紐づく操作を実施します。
- iOS/AndroidアプリはWebアプリにユーザの情報を問い合わせます。
- WebアプリはJINS MEME APIにユーザの情報を問い合わせます。
- iOS/AndroidはJINS MEME APIの問い合わせ結果を表示します。ユーザの認可が取り消されている場合は、Webアプリ経由で認可コードフローを実施して再度アクセストークンを取得する処理を組み込む必要があります。