サブスクリプション・イベント技術実装ガイド

ドキュメント

概要

このドキュメントでは、Singular SDKを使ってサブスクリプションイベントを実装する方法について包括的に説明します。様々なプラットフォームでのアプリ内サブスクリプションイベントのトラッキング、サーバー間(S2S)イベントの統合、RevenueCatやAdaptyのようなサードパーティとの統合について説明しています。

Singularはアプリ内でサブスクリプションと更新をトラッキングし、ユーザー行動と収益生成に関する洞察を提供します。Singularのサブスクリプションアトリビューションは、サブスクリプションイベントを追跡する堅牢な方法を提供し、正確でリアルタイムのデータ収集を保証します。

考慮事項 SDK S2S S2S 3P統合
実装 SDKのカスタム収益メソッドを使用して、Singularに購読イベントを送信します。 お客様のバックエンドで管理されているサブスクリプションイベントを、必要なモバイルデバイスプロパティと共にSingularのREST API(直接S2S実装)に送信します。 S2Sインテグレーションはサードパーティパートナーによって管理され、それぞれのプラットフォームで設定が必要です。
アプリアクティビティへの依存 Singular SDKがサブスクリプションイベントを送信するには、アプリが起動している必要があります。 サブスクリプションイベントは、サーバー間でリアルタイムに送信できます。 サブスクリプションイベントはサードパーティパートナーからリアルタイムで送信されます。
イベントのタイミング イベントの送信はアプリの起動(およびSingular SDKの初期化)に依存するため、Singularに送信されるイベントは実際のサブスクリプション時刻とは異なるイベント時刻になる可能性があります。 サブスクリプションイベントはバックエンドで処理されるため、リアルタイムで送信できます。 サブスクリプションイベントは、3Pベンダーによって処理された後、ほぼリアルタイムで送信できます。

注意

サブスクリプションイベントをS2Sインテグレーション経由で送信する場合でも、ほとんどのお客様はSingular SDKを統合して、セッションと非サブスクリプションイベントを管理する必要があります。

アプリでのサブスクリプション状態管理の実装

GoogleのPlay Billing LibraryとAppleのStoreKitを統合することで、サブスクリプション情報を照会し、デバイス上で直接サブスクリプションの状態を管理することができます。この設定により、Singularの実装方法の1つと統合することができます。以下は、Billing LibraryとStoreKitの簡単な実装を示すサンプルコードです。あなたのアプリのコードやサブスクリプションモデルに合うように、Productionでこれらの例を修正してください。

Android: Google Play 課金ライブラリの統合

1.課金ライブラリをプロジェクトに追加する

build.gradleにGoogle Play Billing Libraryの設定を追加します。

implementation 'com.android.billingclient:billing:6.0.1'

2.アプリ内商品とサブスクリプションの設定

Google Play Consoleでアプリ内商品とサブスクリプションアイテムを設定します。

3.サブスクリプション情報を問い合わせる

BillingClientを使用して、アプリ内の購入履歴と定期購入のステータスを照会します。

KotlinJava
val billingClient = BillingClient.newBuilder(context)
  .setListener(purchaseUpdateListener)
  .enablePendingPurchases()
  .build()
billingClient.startConnection(object : BillingClientStateListener {
  override fun onBillingSetupFinished(billingResult: BillingResult) {
    if (billingResult.responseCode == BillingClient.BillingResponseCode.OK) {
        // The billing client is ready, you can now query subscription information asynchronously


        billingClient.queryPurchasesAsync(BillingClient.SkuType.SUBS) {result, subscriptionList ->
            if (result.responseCode == BillingClient.BillingResponseCode.OK && subscriptionList != null) {
                // Handle the retrieved subscription list


                subscriptionList.forEach { purchase ->
                    // Process each subscription purchase


                }
            } else {
                // Handle error in queryPurchasesAsync


            }
        }
    } else {
       // Handle error on setup finished


    }
  }
  override fun onBillingServiceDisconnected() {
    // Retry connection after a delay if the service gets disconnected


    Handler(Looper.getMainLooper()).postDelayed({
        billingClient.startConnection(this)
    }, 3000)
  }
})
// Remember to properly disconnect the billing client in your activity/fragment lifecycle


override fun onDestroy() {
    billingClient.endConnection()
    super.onDestroy()
}

iOS: StoreKitの統合

1.StoreKitの実装

StoreKit FrameworkをiOSアプリに統合します。

2.アプリ内商品と定期購入の設定

App Store Connectでアプリ内商品とサブスクリプションアイテムを設定します。

3.定期購入情報の照会

SKPaymentQueueとSKReceiptRefreshRequestを使用して、定期購入のステータスとレシート情報を取得します。

Swift
import StoreKit
class YourViewController: UIViewController, SKPaymentTransactionObserver {
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Add the observer for payment transactions


        SKPaymentQueue.default().add(self)
        
        // Refresh the receipt to get the latest subscription information


        refreshReceipt()
    }
    func refreshReceipt() {
        let request = SKReceiptRefreshRequest()
        request.delegate = self
        request.start()
    }
    // Implement SKPaymentTransactionObserver methods


    func paymentQueue(_ queue: SKPaymentQueue, updatedTransactions transactions: [SKPaymentTransaction]) {
        for transaction in transactions {
            switch transaction.transactionState {
            case .purchased, .restored:
                // Handle the purchase or restore


                // You can check the transaction.transactionReceipt for receipt information


                break
            case .failed:
                // Handle the failed transaction


                break
            case .deferred:
                // Handle the deferred transaction


                break
            case .purchasing:
                // Transaction is in progress


                break
            @unknown default:
                break
            }
        }
    }
    // Implement SKRequestDelegate method


    func requestDidFinish(_ request: SKRequest) {
        // Receipt refresh request completed


        // Now you can use the updated receipt to check subscription status


    }
    func request(_ request: SKRequest, didFailWithError error: Error) {
        // Handle the error during the receipt refresh request


    }
}

Singular SDKからサブスクリプションイベントを送信する

上記の実装でサブスクリプションの状態が変更されると、新しいカスタム Revenue イベントを Singular に送信する必要があります。IAP 関数を使用したり、Singular にレシート値を送信しないでください。アプリに実装したSingular SDKの各実装ガイドに従って、レシートなしでcustomRevenue()イベントを送信してください。

  • iOS SDK: このメソッドを使用して "subscription "イベント名を送信します:

    (void)customRevenue:(NSString*)eventname currency:(NSString *)currency
            amount:(double)amount withAttributes:(NSDictionary*)attributes;
  • Android SDKは、このメソッドを使用して "subscription "イベント名を送信します:

    Singular.customRevenue(String eventName, String currency, double
            amount, Map<String, Object> attributes)
  • React Native SDK:このメソッドを使用して、"subscription "イベント名を送信します:

    static customRevenueWithArgs(eventName: string, currency: string,
            amount: number, args: SerializableObject): void;
  • Unity SDK:このメソッドを使用して、"subscription "イベント名を送信します:

    SingularSDK.CustomRevenue(string eventName, string currency, double
            amount, Dictionary<string, object> attributes)
  • Flutter SDK:このメソッドを使用して "subscription "イベント名を送信します:

    Singular.customRevenueWithAttributes(String eventName, String currency, 
            double amount, Map attributes)
  • Cordova SDK: このメソッドを使用して、"subscription "イベント名を送信します:

    SingularCordovaSdk.customRevenueWithArgs(String eventName, String currency, 
            double amount, JSONObject args)

サブスクリプションイベントをS2Sで送信する

サブスクリプションイベントをリアルタイムで送信し、バックエンドでサブスクリプションイベントを管理したい場合は、SingularのREST APIにイベントを送信できます。

Singularにサブスクリプションイベントを送信するには、Event Endpointを使用します。

  • Singular SDKを実装している場合:
    • このオプションを使用してSDKからサブスクリプションイベントを送信する必要はありません。
    • ローンチ(セッション)S2Sエンドポイントと統合する必要はありません。

3P統合によるサブスクリプションイベントの送信

サブスクリプションを管理するためにサードパーティのサービスを使用している場合、それらのベンダーは独自の統合方法でサブスクリプションデータを取得します。そして、各ベンダーのシステムにすでに統合されているSingularのREST APIにサブスクリプションイベントを送信します。これらの統合には、パートナーのプラットフォームでいくつかの設定が必要です:

サブスクリプションイベント

いくつかの異なるサブスクリプションイベントをSingularに送信することができます。以下にSingularの標準イベント名を示しますが(関連SDKドキュメントを参照)、必要に応じてカスタムイベント名を使用することもできます。

サブスクリプションの状態 イベント SDKメソッド S2S統合
サブスクリプション sng_subscribe
  • customRevenueイベントメソッド(レシート検証はサポートされていません)
  • 収益パラメータを含むイベントリクエスト
トライアル開始 sng_start_trial
  • イベントメソッド(収益金額なし)
  • 標準イベント・リクエスト
トライアル終了 sng_end_trial (まだ正式な標準イベントではないため、カスタムイベントとして送信されます)
  • イベント方法(収益金額なし)
  • 標準イベントリクエスト
払い戻し subscription_refunded
  • 負の収益を伴うcustomRevenueイベント・メソッド(オプション)
  • イベント・メソッド(収益金額なし)
  • 収益パラメータと負の収益を持つイベント・メソッド(オプション)
  • 標準イベント・リクエスト
キャンセル サブスクリプション・キャンセル
  • イベント・メソッド(収益金額なし)
  • 標準イベント要求
サブスクリプションの更新 subscription_renewed
  • customRevenueイベント・メソッド(レシート・バリデーションはサポートされません)
  • 収益パラメータを指定したイベント・リクエスト

注意

customRevenue メソッドでサブスクリプションイベントを送信する場合は、isRestored が false のイベントのみを送信するようにしてください。

SKAN測定に関する注意事項

Singularは、上記のすべての統合メソッドでサブスクリプションイベントデータを測定できます。SKANのバージョンによっては、SKANのポストバック測定ウィンドウによってイベント測定が制限される場合があることに注意してください。

ライフサイクルイベント用にSingular SDKを実装し、上記のS2S統合メソッドのいずれかを使用してサブスクリプションイベントを送信する場合は、CSMに連絡してハイブリッドSKANを有効にしてください。