Integrate with the KWS API

KWS API を呼び出して、製品の保護者検証フローをトリガーする方法。

4 分で読めます

PV サービス フローをトリガーするには、製品が send-parent-email API エンドポイント を呼び出す必要があります。

API 統合の詳細を取得する

KWS API を呼び出す際は、アクセスと認証を有効化するための、特定のデータ項目が必要です。

  1. Integration information タブで、以下の詳細をコピーします。

    • Product ID - 製品の KWS ID。
    • Product client ID - 認証 に使用する。
    • Product API key - Developer Access トークン の取得に必要なクライアント シークレット。
    Integration details

    画像をクリックするとフルサイズで表示されます。

  2. Parent Verification タブで、以下の詳細をコピーします。

    • Webhook secret code - KWS からの正当な呼び出しであることを保証するために、ペイロードの署名に使用します。
    • Service API host URL - PV サービスが存在する URL。この URL に対して API クエリを実行する必要があります。
    PV details

    画像をクリックするとフルサイズで表示されます。

注記：各製品にはテストとプロダクションの両方の資格情報があります。正しいセットを必ず使用してください。

ユーザーの詳細を収集する

製品のインターフェースを構成して、以下の項目を収集する必要があります。

  • 保護者のメール アドレス。
  • 子供の場所。これは次のどちらかで指定します。
    • ISO 3166-1 alpha-2 コード。例: 'US'、'GB'、'CA'。
    • 認められた ISO 3166-2 下位区分。例: 'US-CA'、'GB-ENG'、'CA-BC'。
  • 保護者が使用している言語。これは保護者に対するメールと確認画面で KWS が使用する言語です。 例: ‘en’、‘de’、‘ja’。サポートされている言語の完全なリストは KWS プラットフォームでサポートされる言語 を参照してください。

send-parent-email エンドポイントを呼び出す

製品を構成して、収集した保護者のメール アドレス、子供の場所、保護者の言語を、send-parent-email エンドポイントへの認証済み API 呼び出しによって、KWS に送信します。

速度制限

  • 速度制限は、一意の保護者のメール アドレスごとに 1 時間あたり 10 リクエストまでに固定されています。

ユーザー エージェント リクエスト ヘッダー

KWS API へのすべてのリクエストには、クライアントや HTTP ライブラリを識別する空白でない文字列を使用した、ユーザー エージェント ヘッダーを含める必要があります。これを含めない場合、“Request blocked” 403 応答が発生します。

Developer Access トークンで認証する

API の呼び出しは、「Developer Access トークン」と呼ばれる Bearer トークンで認証する必要があります。

Integration information タブで利用できる Product client ID と Product API key (クライアント シークレット) を使用し、トークン エンドポイントによる client_credentials OAuth 許可を介して、KWS の認証サービスから Developer Access トークンを取得します。

注記：上記の認証情報とトークンは、機密情報として扱い、クライアント アプリケーションに渡さないようにしてください。

トークンの取得方法：

注意: デベロッパー アクセス トークンには短い有効期限があり、使用状況によって動的に変更される可能性があります。oauth トークン リクエストへのレスポンスに応じて、トークンの有効期間がわかります (expires_in で、秒単位で表示されます)。トークンの有効期限が切れると、API コールに対して 401 レスポンスが返されるようになります。上記のように新しいアクセス トークンを取得し、リクエストを再試行する必要があります。

API 呼び出しの再試行動作

KWS API に統合するシステムには、API コールの再試行メカニズムが実装されているはずです。再試行メカニズムが実装されている場合、エクスポネンシャル バックオフを実行し、API コールから送信されるレート制限ヘッダーに準拠する必要があります。

KWS が管理するフロー

KWS API を呼び出すと、KWS が検証フロー全体を管理します。

  1. KWS は指定した保護者のメール アドレス宛てにメールを送信し、ID を確認するよう保護者に依頼します。

  2. 保護者はメールに含まれるリンクをクリックして、検証フローを開始します。

  3. KWS が提供する Web ベースのインターフェースに、保護者は検証資格情報を入力できます。子供の場所と、選択した保護者に提示する認証方法 に応じて、さまざまな検証方法を利用できます。

  4. 検証が成功した場合:

    • KWS は、構成済みの webhook を使用して「parent-verified」イベントをシステムに返します。
    • 保護者のメール アドレスのハッシュが KWS ParentGraph 内に格納されます。これにより KWS は、次回 PV サービスの処理を行う際に、保護者が事前に検証済みかどうかを判断します。

事前に検証済みの保護者は、検証の資格情報を提供する必要がありません。「事前に検証済み」とは、ハッシュ化した保護者のメール アドレスが ParentGraph 内に含まれていること、およびアクセスされる製品に対して有効な (または検証時に有効だった) 検証方法を使用し、以前に KWS PV サービスによって保護者が検証済みであることを意味します。

  • KWS は保護者に確認メールを送信し、検証が問題なく終了し、ParentGraph に追加されたことを通知します。(ParentGraph を無効にするリンクも記載されます。)支払いをベースとした検証方法の場合、子どもの居住国における規定に従い、認証、請求、返金などの情報がメールに記載されます。
  • デベロッパー ポータルで Redirect URL を指定した 場合、KWS は保護者をその URL にリダイレクトします。 指定していない場合、KWS は検証成功のメッセージを PV サービスの Web ページ内に表示します。

KWS が保護者に対して提供するメールおよびウェブ ブラウザの例については、「PV サービスのユースケース」を参照してください。

次のステップ

PV サービスにカスタム ブランディングを適用します。