Paddleとの初期連携

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

この連携では、ウェブ経由の購入を管理し、アプリ内課金と並行して、モバイルアプリへのアクセスと分析データを同期します。

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

アプリ内課金とウェブサイト購入の両方のサブスクリプションデータを一元管理する
ウェブサイトで購入したユーザーに、モバイルアプリの有料機能へのアクセスを付与する
すべての販売チャネルの分析データとサブスクリプションデータを1つのダッシュボードで確認する

Appleは現在、米国のApp Storeアプリに外部決済システムへのリンクを含めることを許可していますが、アプリ内購入と外部オプションの両方を提供する必要がある場合もあります。お使いの地域とアプリカテゴリに適用される最新のApp Storeガイドラインをご確認ください。

この連携は、PaddleのウェブからのアプリへのAの追跡と同期に焦点を当てています。ユーザーをアプリからウェブチェックアウトに誘導する必要がある場合は、Adaptyのウェブペイウォールをご利用ください。

Paddle連携を設定するには、以下の手順に従ってください：

1. PaddleをAdapyに接続する

この連携では、ウェブフックを使用してPaddleからAdapyにサブスクリプションデータを送信します。AdapyとPaddleアカウントを接続するには、以下が必要です：

Paddle APIキーを提供する
AdapyのウェブフックURLをPaddleに追加する

以下の手順は、本番環境とテスト環境の両方に適用されます。同時に両方を設定できます。記載のリンクは本番環境用です。テスト環境のリンクを取得するには、各URLの先頭にsandbox-を追加してください。例えば、https://vendors.paddle.com/authentication-v2の代わりにhttps://sandbox-vendors.paddle.com/authentication-v2を使用します。

1.1. Paddle APIキーの取得と追加

PaddleでDeveloper Tools → Authenticationに移動し、New API keyをクリックします。

キーに名前を付け、有効期限を設定します。AdapyでAPIキーを機能させるには、すべてのエンティティに対してRead権限を付与する必要があります。Saveをクリックします。

Copy keyをクリックします。

AdaptyでApp Settings → Paddleに移動し、Paddle API keyセクションにキーを貼り付けます。

Paddle APIキーに有効期限を設定した場合、有効期限が切れる前に手動で新しいキーを生成し、Adaptyで更新する必要があります。キーが期限切れになると、警告なしに連携が停止し、ユーザーが購入できなくなります。

1.2. Adaptyに送信するイベントの追加

AdapyのPaddleページからWebhook URLをコピーします。
PaddleでDeveloper Tools → Notificationsに移動し、New destinationをクリックしてウェブフックを追加します。

ウェブフックにわかりやすい名前を付けます。後で簡単に見つけられるよう、名前に「Adapty」を含めることをお勧めします。
AdapyからコピーしたWebhook URLをURLフィールドに貼り付けます。正しい環境のウェブフックを使用していることを確認してください。
Notification typeをWebhookに設定します。

以下のイベントを選択します：
- subscription.created
- subscription.updated
- transaction.created
- transaction.updated
- adjustment.created
- adjustment.updated

Save destinationをクリックしてウェブフックの設定を完了します。

1.3. ウェブフックシークレットキーの取得と追加

Notificationsウィンドウで、作成したウェブフックの横にある三点ドットをクリックし、Edit destinationを選択します。
Edit destinationパネルにSecret keyという新しいフィールドが表示されます。それをコピーします。

AdaptyでApp Settings → Paddleに移動し、Notification secret keyフィールドにキーを貼り付けます。このキーはAdapyでウェブフックデータを検証するために使用されます。

1.4. PaddleのカスタマーとAdapyのプロファイルを対応付ける

Adaptyは、アプリ内で使用できるよう各購入をカスタマープロファイルに紐付ける必要があります。デフォルトでは、AdapyがPaddleからウェブフックを受信したときにプロファイルが自動的に作成されます。Adaptyのcustomer_user_idとして使用する値を選択できます：

デフォルト・推奨： custom_dataフィールドで渡すcustomer_user_id（Paddleドキュメント参照）
PaddleのCustomerオブジェクトのemail（Paddleドキュメント参照）
ctm-...形式のPaddle Customer ID（Paddleドキュメント参照）
プロファイルを作成しない。カスタマープロファイルをより細かく制御して自分で管理したい場合はこのオプションを選択します。

使用する値はApp Settings → PaddleのProfile creation behaviorフィールドで設定できます。

2. AdapyにPaddleプロダクトを追加する

PaddleプロダクトをAdapty ダッシュボードに追加するか、既存のプロダクトにPaddleプロダクトIDを追加してください。Adaptyは、これらのプロダクトに紐付いたトランザクションのイベントのみを追跡します。この手順をスキップすると、トランザクションイベントが作成されません。

PaddleはApp StoreやGoogle Playと同様にAdapyで動作します。つまり、デジタルプロダクトを販売するもう一つのプラットフォームです。設定するには、AdaptyのProductsセクションで、Paddleの関連するproduct_idとprice_idの値を追加します。

Paddleでは、プロダクトIDはpro_...、価格IDはpri_...の形式です。特定のプロダクトを開くと、Paddleプロダクトカタログで確認できます：

プロダクトを追加したら、次のステップはAdapyが購入を正しいユーザーに紐付けられるようにすることです。

3. モバイルでユーザーにアクセスを付与する

ウェブで購入したユーザーがモバイルでもアクセスできるようにするには、購入時に渡したものと同じcustomer_user_idを使ってAdapty.activate()またはAdapty.identify()を呼び出します。詳細はユーザーの識別をご覧ください。

4. 連携をテストする

すべての設定が完了したら、連携をテストできます。PaddleのTest環境で行われたトランザクションはAdapyにTestとして表示されます。本番環境のトランザクションはProductionとして表示されます。

連携が完了しました。ユーザーはウェブサイトでサブスクリプションを購入し、モバイルアプリのプレミアム機能に自動的にアクセスできるようになります。また、統合されたAdapy ダッシュボードですべてのサブスクリプション分析を追跡できます。

重要な注意事項

Adaptyの分析では、トランザクション金額に税金とPaddle手数料が含まれます。これはPaddleダッシュボードとは異なり、Paddleでは税金と手数料を差し引いた金額が表示されます。そのため、Adaptyに表示される数値はPaddleダッシュボードの数値より高くなります。
他のストアとは異なり、Paddleでの返金は特定のトランザクションのみに影響し、サブスクリプションを自動的にキャンセルしません。サブスクリプションは明示的にキャンセルされない限り有効なままです。
custom_dataフィールドにvariation_idを含めることで、購入を特定のペイウォールインスタンスに紐付けることもできます。Adaptyはウェブフックからこのデータを処理し、分析に含めます。

有料トライアル

Paddleで有料トライアルを使用する場合、Adaptyで2つのプロダクトを作成する必要があります：

非サブスクリプションプロダクトを作成し、トライアル期間の料金を請求するPaddle価格に紐付けます。
サブスクリプションプロダクト（月次/週次など）を作成し、無料トライアルコンポーネントを持つPaddle価格に紐付けます。

Paddleの観点では、これは1つのプロダクトに2つの価格が含まれる単一のトランザクションです。1つはトライアル料金（例：$0.99）、もう1つは無料トライアル（$0.00）の価格です。

Adaptyの観点では、これにより2つの別々のイベントが作成されます：トライアル支払いの非サブスクリプション購入と、サブスクリプションプロダクトのトライアル開始イベントです。

例えば、ユーザーが月額$9.99のサブスクリプションに対して$0.99の有料トライアルを開始すると、Paddleは両方の価格を含む1つのトランザクションを作成しますが、Adaptyはこれを$0.99の非サブスクリプション購入（即時支払い）と$0.00のトライアル開始イベント（将来的に月額$9.99のサブスクリプション）として処理します。

ユーザーが有料トライアルをキャンセルすると、Trial expiredとTrial renewal canceledイベントが発生します。

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

PaddleイベントをインテグレーションS（integrations）で動作させるには、ユーザーが少なくとも一度App Store / Google Playアカウントでアプリにログインする必要があります。

Paddleとの連携が完了すると、Adaptyはすぐに分析情報を提供できる状態になります。Paddleデータを最大限に活用するには、追加のAdapy連携を設定してPaddleイベントを転送し、すべてのサブスクリプション分析を単一のAdapy ダッシュボードに集約できます。

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

現在の制限事項

キャンセル: Paddleにはサブスクリプションキャンセルの2つのオプションがあります：
1. 即時キャンセル：サブスクリプションが即座にキャンセルされます。
2. 期間終了時のキャンセル：現在の請求期間が終了した時点でサブスクリプションがキャンセルされます（アプリストアのアプリ内サブスクリプションと同様）。
返金: Adaptyは全額返金と部分返金を追跡します。
グレース期間: デフォルトでは、Paddleは請求の問題に対して30日間の固定グレース期間を適用し、その間サブスクリプションは有効なままです。グレース期間の長さと期間終了後のアクション（サブスクリプションの一時停止またはキャンセル）はカスタマイズできます。

トライアル: トライアル終了後に支払いの収集が失敗した場合、サブスクリプションのステータスはpast_dueに変わります。本番環境では、PaddleのRetainがダニングウィンドウを適用してサブスクリプションがキャンセルまたは一時停止される前に支払い回収を試みます。サンドボックスではRetainが利用できないため、支払いの再試行は行われず、サブスクリプションは無期限でpast_dueのままになります。

関連情報：

PaddleでのPurchaseを検証し、アクセスレベルを取得し、PaddleのトランザクションHistory をサーバーサイドAPIでインポートする