Stripeとの初期連携

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

このインテグレーションは、Web経由の購入（Stripeチェックアウト、ホスト型決済ページ、ペイメントリンク、カスタムWebフローなど）を対象とし、モバイルアプリのアクセスと分析を同期します。

以下のようなケースで役立ちます：

• Webで購入後にアプリをインストールしてアカウントにログインしたユーザーに、有料機能へのアクセスを自動的に付与する
• サブスクリプションの分析データ（コホート、予測、その他の分析ツール一式を含む）をすべて単一のAdapty ダッシュボードで管理する

ウェブ購入はアプリにおいてますます普及していますが、Apple App Store はデジタルコンテンツのアプリ内課金とは異なる仕組みを、米国内に限り認めています。他の国々でウェブサブスクリプションをアプリ内でプロモーションしないよう注意してください。そうしないと、アプリが却下またはBANされる可能性があります。

以下の手順では、Stripe インテグレーションの設定方法を説明します。

1. StripeをAdaptyに接続する

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

0. テストモードとライブモードのどちらでStripeを接続するかを決めます。最初にテストモードで設定する場合は、後でライブモードでも同じ手順を繰り返す必要があります。

1. Stripe App MarketplaceにアクセスしてAdatyアプリをインストールします。サンドボックスモードではアプリのインストールに対応していないため、本番環境またはテストモードでのみ実行できます。

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

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

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

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

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

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

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

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

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

4. AdaptyのWebhook URLを Endpoint URL フィールドに貼り付けます。次にWebhookの Version フィールドで Latest API version を選択します。その後、以下のイベントを選択します：

• charge.refunded
  • checkout.session.completed
  • customer.subscription.created
  • customer.subscription.deleted
  • customer.subscription.paused
  • customer.subscription.resumed
  • customer.subscription.updated
  • invoice.created
  • invoice.updated
  • payment_intent.succeeded

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

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

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

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

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

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

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

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

4. ウェブ上での購入にユーザー ID を紐づける

Adapty は、ユーザーのアクセスレベルを付与・更新するための唯一の情報源として Stripe からの Webhook に依存しています。ただし、この連携を正しく機能させるには、Stripe と連携する際にあなた側から追加情報を提供する必要があります。

アクセスレベルをプラットフォーム間（ウェブやモバイルなど）で一貫して管理するには、Adapty がウェブフックから識別できる単一のユーザー ID を用意する必要があります。これはユーザーのメールアドレス、電話番号、または利用している認証システムの任意の ID です。Adapty ではこの値を customer_user_id と呼びます。

Adaptyは、App Settings → StripeのProfile creation behaviorで選択された1つのソースからユーザーIDを読み取ります。これはフォールバックチェーンではありません。選択したソースが特定のトランザクションで空の場合、StripeデータのどこかにIDが存在していても、その購入は匿名のままになります。利用可能なすべてのソースについては、Profile creation behaviorを参照してください。

Stripeで購入を作成する方法に合ったオプションを選択してください。

Stripe API を使用して作成されるチェックアウトセッションとサブスクリプション

Profile creation behavior は Use customer_user_id from metadata (default) のままにしておきます。次に、Stripe を通じて決済を初期化しているコード部分を開き、Stripe Subscription（sub_...）または Checkout Session オブジェクト（ses_...）の metadata オブジェクトに、次のようにユーザー ID を customer_user_id として追加します：

{'customer_user_id': "YOUR_USER_ID"}

これだけのシンプルな追加が、コードに必要な唯一の作業です。あとは Adapty が Stripe から受け取るすべてのウェブフックを解析し、この metadata を抽出してサブスクリプションを正しくカスタマーに紐付けます。

Payment Links（コードなし）

Stripe Payment Links を使って販売していて、metadata を設定するバックエンドがない場合は、リンクの client_reference_id クエリパラメータにユーザー ID を渡してください：

https://buy.stripe.com/your_link?client_reference_id=YOUR_USER_ID

Stripe はこの値を Checkout Session に保存し、checkout.session.completed イベントで Adapty に送信します。サブスクリプションと買い切り購入のどちらにも対応しています。

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

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

6. 連携をテストする

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

プロファイル作成の挙動

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

1. デフォルト・推奨: メタデータの customer_user_id を使用 — 上記のステップ 4 でメタデータに指定した customer_user_id
2. Stripe の Customer オブジェクトのメールアドレスを使用（Stripe のドキュメントを参照）
3. Stripe の Session オブジェクトの client_reference_id を使用（Stripe のドキュメントを参照）— Payment Links と組み合わせて使用するオプション

App Settings → Stripe でどのIDを使用するかを設定できます。Adaptyはここで選択したソースのみをアプリ内のすべてのStripeトランザクションに使用します。他のソースへのフォールバックはありません。

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

現在の制限事項

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

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

キャンセル

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

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

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

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

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

返金

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

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

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

なぜ重要なのか

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

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

一意性を確保する方法

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

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

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

1. Stripeダッシュボードでテストモードに切り替えます。
2. Settings → Billing → Invoicesに移動します。
3. Invoice numbering を Sequentially across your account に設定します。
4. Invoice prefix を TEST-（またはテスト環境固有の任意のプレフィックス）に設定します。
5. ライブモードに切り替えて、手順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を通じて行われたcheckout.session.completedイベントの買い切り（非サブスクリプション）購入を記録します。StripeのAdaptyウェブフックエンドポイントでこのイベントが有効になっていることを確認してください。AdaptyがPayment Linksサポートを追加する前に作成されたエンドポイントにはこのイベントが含まれていません。確認方法については手順4を参照してください。

Adaptyはセッションの最初の明細項目からプロダクトを取得するため、複数のプロダクトを販売するセッションでは最初のプロダクトのみが記録されます。

Stripe はこれらの購入に対する返金をまだ適用していません: Stripe は charge.refunded を送信しますが、Adapty は Checkout または Payment Link を通じて購入した買い切り購入のアクセスを取り消しません。サブスクリプションおよび Stripe インボイスを通じて請求された買い切り購入の返金は通常通り機能します。

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

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

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

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

• Amplitude
• Webhook
• Firebase
• Mixpanel
• Posthog

サポートされている Stripe イベント

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

• charge.refunded
• checkout.session.completed
• customer.subscription.created
• customer.subscription.deleted
• customer.subscription.paused
• customer.subscription.resumed
• customer.subscription.updated
• invoice.created
• invoice.updated
• payment_intent.succeeded