インストール

ショップにアプリを追加する処理を「インストール」といいます。

インストールによって行われる処理

ショップオーナーがアプリをインストールしたとき、以下の処理をカラーミーショップが行います。

• 選択された料金プランに基づき課金開始
• インストールフックの呼び出し

ショップオーナーがアプリをインストールしたとき、アプリストア上で発生する挙動は以下の通りです。

• 利用中のアプリ一覧 (opens new window)にインストールされたアプリが表示される
• 利用中のアプリ一覧のアプリ名をクリックすると申請時に設定された アプリ設定ページ等URL に遷移する

インストールフック

アプリのインストール時に、インストールに関する情報を POST メソッド、 application/json 形式で通知します。 通知先のURLはカラーミーショップ デベロッパーページ (opens new window)にログインし、各アプリストア アプリのアプリ設定から登録してください。

以下のパラメータが送信されます。課金請求に必要なパラメータを含むので、必ず受け取れるようにしてください。

パラメータ	機能	形式
account_id	インストールしたショップオーナーのアカウントID	PA+8桁の整数
application_charge_source_id	プラン課金ID	数字と大文字アルファベットで構成される文字列(6桁以上)
recurring_application_charge_id	（月額課金の場合）課金契約ID	数字と大文字アルファベットで構成される文字列(6桁以上)
application_charge_id	（買い切りの場合）課金契約ID	数字と大文字アルファベットで構成される文字列(6桁以上)
trial_term	（無料お試し期間がある場合）無料お試し期間	JSONオブジェクト
mail	ショップオーナーへの連絡メールアドレス	文字列

application_charge_source_id はインストール時に選択されたプラン課金の判別にご利用ください。 recurring_application_charge_id は従量課金APIによる従量課金データの作成 (opens new window)に必要ですので、記録いただくようお願いします。

mail パラメータの値はショップオーナーへの連絡手段としてご利用いただけます。インストール後に認可フローが中断され、アクセストークンが得られない際のショップオーナーへの連絡手段としてご活用いただけます。このパラメータはカラーミーショップの非公開情報として登録されている値です。前述の用途以外でこの値を使用しないでください。

例) 買い切りの場合

{
  "account_id": "PA00000001",
  "application_charge_source_id": "F3RN9A",
  "application_charge_id": "A3FT4N",
  "mail": "shop@example.com"
}

例) 月額課金の場合

{
  "account_id": "PA00000001",
  "application_charge_source_id": "F3RN9A",
  "recurring_application_charge_id": "A3FT4N",
  "mail": "shop@example.com"
}

課金設定で無料お試し期間を設定した場合、以下の情報を trial_term パラメータとして送信します。 無料お試し期間中は従量課金APIを呼び出して課金請求することはできません。

パラメータ	機能	形式
starts_at	無料お試し開始日時	整数値(UNIXタイムスタンプ)
ends_at	無料お試し終了日時	整数値(UNIXタイムスタンプ)

例) 無料お試し期間がある月額課金の場合

{
  "account_id": "PA00000001",
  "application_charge_source_id": "F3RN9A",
  "recurring_application_charge_id": "A3FT4N",
  "mail": "shop@example.com",
  "trial_term" {
    "starts_at": 1565017200,
    "ends_at": 1567609200
  }
}

受け取りに成功した場合は、以下のパラメータを application/json 形式でレスポンスボディに付与し、 ステータスコード 200 レスポンスをカラーミーショップへ返却してください。 ステータスコード 200 レスポンスをカラーミーショップが受け取れない場合、もしくは以下のパラメーターが返却されなかった場合、インストールを中止し、インストールによって発生した情報は破棄されます。

パラメータ	機能	形式
redirect_url	インストール成功後に遷移するURL	文字列（URL）

例)

{
  "redirect_url": "https://example.com"
}

インストール完了後、インストールフックのレスポンスパラメータの redirect_url より先の画面で認可コード・アクセストークンの取得に必要な各種処理の実装 (opens new window)を行ってください。

フックの署名検証

X-Appstore-Signature リクエストヘッダーに含まれる署名を検証して、リクエストがカラーミーショップから送信されたことを確認してください。

検証の手順は以下のとおりです。

1. カラーミーショップが発行した webhook_secret を秘密鍵として、HMAC-SHA256アルゴリズムを使用してリクエストボディのダイジェスト値を取得します。
2. ダイジェスト値をBase64エンコードした値とリクエストヘッダーに付与された署名( X-Appstore-Signature の値）が一致することを確認します。

サンプルコード(Ruby)

WEBHOOK_SECRET = 'my_webhook_secret'

payload_body = request.body.read
signature = Base64.strict_encode64(OpenSSL::HMAC.digest('sha256', WEBHOOK_SECRET, payload_body))
ActiveSupport::SecurityUtils.secure_compare(signature, request.env['HTTP_X_APPSTORE_SIGNATURE'])