Stripeとの初期連携

Adaptyは、Stripeを通じたウェブ決済・サブスクリプションを追跡することで、web2appのサブスクリプションフローをサポートしています。

この連携は、ウェブ起点の購入（Stripe Checkout、ホスト型決済ページ、またはカスタムウェブフロー）に対応しており、モバイルアプリのアクセスやアナリティクスと同期します。

以下のようなシナリオで役立ちます：

ウェブで購入した後にアプリをインストールしてログインしたユーザーに、有料機能へのアクセスを自動的に付与する
コホート、予測、その他のアナリティクスツールを含む、すべてのサブスクリプションアナリティクスをAdapty ダッシュボード一か所で管理する

ウェブ購入はアプリにとってますます一般的になりつつありますが、Apple App Storeがアプリ内課金以外のシステムを許可しているのはアメリカ国内のデジタルコンテンツに限られています。他の国でウェブサブスクリプションをアプリ内で宣伝しないようにしてください。違反するとアプリが審査で却下されたり、BANされる可能性があります。

以下の手順でStripe連携を設定します。

この連携は、Stripeのウェブ購入の追跡と同期を目的としています。アプリからウェブチェックアウトにユーザーを誘導する場合は、ウェブペイウォールをご覧ください。

1. StripeをAdaptyに接続する

この連携は主に、AdaptyがWebhook経由でStripeからサブスクリプションデータを取得することで機能します。そのため、APIキーを提供し、AdaptyのWebhook URLをStripeに設定することで、AdaptyアカウントとStripeアカウントを接続する必要があります。Webhookのセットアップをできるだけラクにするために、StripeにAdatyアプリをインストールしてください：

以下の手順はStripeのProductionモードとTestモードで共通ですが、それぞれ異なるAPIキーを使用する必要があります。

テストモードとライブモードのどちらでStripeを接続するかを決めます。最初にテストモードで設定する場合は、後でライブモードでも同じ手順を繰り返す必要があります。
Stripe App MarketplaceにアクセスしてAdatyアプリをインストールします。サンドボックスモードではアプリのインストールに対応していないため、本番環境またはテストモードでのみ実行できます。

アプリに必要な権限を付与します。これにより、Adaptyがサブスクリプションデータと履歴にアクセスできるようになります。その後、Continue to app settings をクリックして続行します。

権限ポップアップの下部で、ライブモードまたはテストモードのどちらでアプリをインストールするかを選択できます。

ポップアップで新しい制限付きキーを生成します。メール、Touch ID、またはセキュリティキーを使って本人確認が必要です。キーを生成した後は再度確認できないため、パスワードマネージャーや秘密管理ストアに安全に保存してください。

ポップアップから生成されたキーをコピーし、AdaptyのApp Settings → Stripeに移動します。モードに合わせて Stripe App Restricted API Key セクションにキーを貼り付けます。テストモードとライブモードでは異なるキーを生成する必要があることに注意してください。

以上で完了です！次は、Stripeでプロダクトを作成してAdaptyに追加しましょう。

非推奨のインストールフロー

StripeのDevelopers → API Keysに移動します：

6549602-CleanShot_2023-12-06_at_17.29.122x.webp

Secret key タイトルの横にある Reveal live (test) key button をクリックしてキーをコピーし、AdaptyのApp Settings → Stripeに移動します。ここにキーを貼り付けます：

2989508-CleanShot_2023-12-07_at_14.59.122x.webp

次に、AdaptyのStripe設定ページ下部からWebhook URLをコピーします。StripeのDevelopers → Webhooksに移動し、Add endpoint ボタンをクリックします：

e7149f5-CleanShot_2023-12-07_at_17.31.392x.webp

AdaptyのWebhook URLを Endpoint URL フィールドに貼り付けます。次にWebhookの Version フィールドで Latest API version を選択します。その後、以下のイベントを選択します：
- charge.refunded
- customer.subscription.created
- customer.subscription.deleted
- customer.subscription.paused
- customer.subscription.resumed
- customer.subscription.updated
- invoice.created
- invoice.updated
- payment_intent.succeeded

cbc5404-CleanShot_2023-12-07_at_17.36.232x.webp

“Add endpoint” を押し、“Signing secret” の下にある “Reveal” を押します。これはAdapty側でWebhookデータを復号するために使用されるキーです。表示後にコピーしてください：

0460cbb-CleanShot_2023-12-07_at_17.52.582x.webp

最後に、このキーをAdaptyの App Settings → Stripe の “Stripe Webhook Secret” に貼り付けます：

055db20-CleanShot_2023-12-07_at_14.56.212x.webp

2. Stripeでプロダクトを作成する

テストモードで設定している場合は、この手順を続ける前にStripeもTestモードに切り替えてください。

StripeのProduct catalogにアクセスし、販売したいプロダクトと料金プランを作成します。Stripeでは1つのプロダクトに複数の料金プランを設定できるため、プロダクトを追加作成しなくてもオファーを柔軟に調整できます。

b202e2e-CleanShot_2023-12-06_at_15.06.262x.webp

現時点でAdaptyがサポートしているのは、Flat rate（例：$9.99/月）または Package pricing（例：$9.99/10ユニット）のみです。これらはアプリストアと同様の動作をします。Tiered pricing、Usage-based fee、Customer chooses price のオプションはサポートされていません。

3. StripeプロダクトをAdatyに追加する

プロダクトは必須です！Adapty ダッシュボードでStripeプロダクトを作成してください。Adaptyはこれらのプロダクトに紐づいたトランザクションのイベントのみ追跡します。このステップをスキップすると、トランザクションイベントが作成されません。

AdaptyではStripeをApp StoreやGoogle Playと同様に扱います。つまり、デジタルプロダクトを販売する別のストアとして設定します。設定方法も同様で、StripeプロダクトのIDを（product_idとprice_idを）AdaptyのProductsセクションに追加するだけです：

StripeのプロダクトIDは prod_...、価格IDは price_... の形式になっています。StripeのProduct Catalogでプロダクトを開けば、簡単に確認できます：

14a72d7-CleanShot_2023-12-06_at_17.32.512x.webp

必要なプロダクトをすべて追加したら、次はStripeに購入者のユーザーIDを伝える設定をしましょう。これにより、AdaptyがStripeからの情報を正しく取り込めるようになります。

4. ウェブ購入にユーザーIDを付加する

Adaptyは、アクセスレベルの付与・更新において、Stripeからのwebhookを唯一の情報源として利用しています。ただし、この連携を正しく機能させるためには、Stripe連携時にお客様側から追加情報を提供する必要があります。

プラットフォーム（ウェブまたはモバイル）を横断して一貫したアクセスレベルを維持するには、AdaptyがWebhookから認識できる単一のユーザーIDに依存する必要があります。これはユーザーのメールアドレス、電話番号、または利用している認証システムのその他のIDが使えます。

ユーザーを識別するためにどのIDを使用するかを決めてください。次に、Stripeで決済を初期化しているコード部分にアクセスし、そのユーザーIDをStripe Subscription（sub_...）またはCheckout Sessionオブジェクト（ses_...）のmetadataにcustomer_user_idとして以下のように追加してください：

{'customer_user_id': "YOUR_USER_ID"}

コードに必要な変更はこれだけです。これにより、AdaptyはStripeから受け取ったすべてのWebhookを解析し、このmetadataを抽出して、サブスクリプションを正しくユーザーに紐付けます。

ユーザーIDは必須です

これがなければ、ユーザーを特定してモバイル側でアクセスレベルを付与する方法がありません。

metadataにcustomer_user_idを指定しない場合は、AdaptyがStripeの他の情報からIDを探すよう設定できます：StripeのCustomerオブジェクトのemail、またはStripeのSessionのclient_reference_idのいずれかです。

プロファイル作成の挙動の設定方法についてはこちらをご覧ください。

StripeのCustomerも必須です

Checkout Sessionsを使用している場合は、customer_creationをalwaysに設定してStripe Customerを作成するようにしてください。

5. モバイルユーザーへのアクセス付与

ウェブから来たモバイルユーザーが有料機能にアクセスできるようにするには、前のステップで提供したのと同じcustomer_user_idを使ってAdapty.activate()またはAdapty.identify()を呼び出すだけです（詳細はユーザーの識別 iOS、Android、React Native、Flutter、Unity をご覧ください）。

6. 連携をテストする

サンドボックスと本番環境の両方で上記の手順を完了したことを確認してください。StripeのTestモードで行ったトランザクションは、AdaptyではSandboxとして扱われます。

以上で完了です！

ユーザーはウェブで購入を完了し、アプリで有料機能にアクセスできるようになります。また、すべてのサブスクリプションアナリティクスを1か所で確認できます。

プロファイル作成の挙動

Adaptyは購入をモバイルで利用可能にするために、顧客プロファイルに紐付ける必要があります。そのため、デフォルトではStripeからWebhookを受信した際にプロファイルを作成します。Adaptyで顧客ユーザーIDとして使用するものを選択できます：

デフォルトかつ推奨： 上記のステップ4でmetadataに指定したcustomer_user_id
StripeのCustomerオブジェクトのemail（Stripeのドキュメントを参照）
StripeのSessionオブジェクトのclient_reference_id（Stripeのドキュメントを参照）

使用するIDはApp Settings → Stripeで設定できます。

注意： 特定のStripeトランザクションに指定したIDが含まれていない場合、プロファイルは一切作成されません。このトランザクションは、何らかのプロファイルに紐付けられるまで匿名のままになります（例えば、後からS2S validateを使ってこのトランザクションを手動で通知した場合など）。

アナリティクスには表示されますが、プロファイルのカウントに依存するセクション（LTV、コホート、コンバージョンなど）には反映されず、イベントフィードでも確認できません。

プロファイルをまったく作成しないという4つ目の選択肢もありますが、上記のアナリティクス制限があるため推奨しません。

現在の制限事項

アップグレード、ダウングレード、日割り計算

サブスクリプションのアップグレードやダウングレードを行うと、日割り計算による請求が発生することがあります。Adaptyはこれらの請求を収益計算に含めません。Stripeダッシュボードからこれらのオプションを手動で無効にするか、Stripe APIでproration_behaviour属性の値をnoneに設定して無効にすることをお勧めします。

キャンセル

Stripeにはサブスクリプションのキャンセルオプションが2つあります：

即時キャンセル：日割り計算の有無にかかわらず、サブスクリプションが即座にキャンセルされます
期間終了時のキャンセル：現在の請求期間の終了時にキャンセルされます（アプリストアのアプリ内サブスクリプションと同様）。

Adaptyはどちらのオプションにも対応していますが、即時キャンセルの場合、収益計算で日割り計算オプションは考慮されません。

請求の問題とグレース期間

顧客の支払いに問題が発生すると、Adaptyは請求問題イベントを生成し、アクセスが取り消されます。Stripeのグレース期間はまだサポートしていませんが、将来のリリースで対応予定です。

返金

Adaptyが追跡するのは全額返金のみです。日割り計算による返金や部分返金は現在サポートしていません。

トランザクションIDの一意性

Adaptyはstore_transaction_idとstore_original_transaction_idを使用してプロファイルとトランザクションを照合します。これらはテスト環境と本番環境の間で一意である必要があります。

なぜ重要なのか

同じトランザクションIDが両方の環境に存在すると、Adaptyはそれらを1つのトランザクションとして扱い、以下の問題が発生します：

本番環境の購入がテスト環境のアクセスレベルとプロダクトIDを引き継ぐ
APIレスポンスでプロダクトIDと環境の情報が誤って表示される
プロファイルの紐付けとサブスクリプションイベントが正しく機能しない

一意性を確保する方法

StripeのインボイスIDはテスト環境とライブ環境で重複する可能性があります。環境をまたいだIDの衝突を防ぐには、以下のいずれかの方法を選択してください。

オプション1：環境プレフィックス付きのアカウントレベルの採番

各環境に対して個別にプレフィックスを設定します：

Stripeダッシュボードでテストモードに切り替えます。
Settings → Billing → Invoicesに移動します。
Invoice numbering を Sequentially across your account に設定します。
Invoice prefix を TEST-（またはテスト環境固有の任意のプレフィックス）に設定します。
ライブモードに切り替えて、手順2〜4を繰り返します。プレフィックスには LIVE-（またはライブ環境固有の任意のプレフィックス）を使用します。

オプション2：顧客レベルの採番

Stripe settings -> Billing -> Invoices タブの Invoice numbering を Sequentially for each customer (customer-level) に設定します。

上記の設定を行っても、インボイスを削除するとStripeが同じ顧客の新しいインボイスに同じIDを再利用する場合があります。インボイスはできるだけ削除しないようにすることをお勧めします。

Stripe CheckoutまたはPayment Linksを使った買い切り購入

AdaptyがStripe Checkout（mode=payment）またはPayment Linksを通じた買い切り（非サブスクリプション）購入を追跡するのは、Stripeがその購入に対してインボイスを生成した場合のみです。デフォルトでは、Stripeは買い切りのCheckout購入に対してインボイスを作成しません。この場合、payment_intent.succeededはインボイスデータなしで到達するため、Adaptyがトランザクションを記録するには不十分です。

Adaptyで買い切りCheckout購入を追跡するには、セッション作成時にインボイスの作成を有効にしてください。これにより、Stripeがインボイスを生成し、関連するinvoice.createdおよびinvoice.updatedイベントを送信します。Adaptyはこれらのイベントを処理してトランザクションを記録します。

Stripeデータをさらに活用する

Stripeと連携すると、Adaptyはすぐにインサイトを提供できる状態になります。Stripeデータを最大限に活用するには、追加のAdapty連携を設定してStripeのイベントを転送しましょう。これにより、すべてのサブスクリプションアナリティクスをAdapty ダッシュボード一か所に集約できます。

アナリティクスをさらに強化するために、Stripeのmetadataにvariation_idを含めると、購入を特定のペイウォールインスタンスに紐付けることができます。これは、特定のペイウォールの表示がコンバージョンにつながったかどうかを追跡したい場合など、自社製ウェブペイウォールの実装時に特に有用です。

variation_idは、Stripe Subscription（sub_...）とCheckout Session（ses_...）オブジェクトのmetadataからのみ読み取られます：

{
  'customer_user_id': "YOUR_USER_ID",
  'variation_id': "YOUR_VARIATION_ID"
}

Stripeイベントの転送・分析に使用できる連携：

サポートしているStripeイベント

Adaptyは以下のStripeイベントをサポートしています：

charge.refunded
customer.subscription.created
customer.subscription.deleted
customer.subscription.paused
customer.subscription.resumed
customer.subscription.updated
invoice.created
invoice.updated
payment_intent.succeeded