订阅事件技术实施指南

文件

概述:

本文档全面介绍了如何使用 Singular SDK 实现订阅事件。它涵盖了跨各种平台的应用程序内订阅事件跟踪、服务器到服务器(S2S)事件集成以及 RevenueCat 和 Adapty 等第三方集成。

通过 Singular,您可以在应用程序中跟踪订阅和续订情况,深入了解用户行为和创收情况。Singular 的订阅归因功能提供了强大的订阅事件跟踪方法,确保了数据收集的准确性和实时性。

注意事项 SDK S2S S2S 3P 集成
实施 通过SDK中的自定义Revenue方法向Singular发送订阅事件 将后台管理的订阅事件发送到Singular的REST API(直接S2S实施),并提供所需的移动设备属性 S2S集成由第三方合作伙伴管理,需要在其各自的平台中进行配置。
依赖应用程序活动 应用程序必须启动,Singular SDK 才能发送订阅事件 订阅事件可在服务器到服务器之间实时发送 订阅事件由第三方合作伙伴实时发送
事件定时 由于发送事件依赖于应用程序的启动(以及 Singular SDK 的初始化),因此发送到 Singular 的事件时间可能与实际订阅时间不同。 订阅事件可在后台处理过程中实时发送 订阅事件经 3P 供应商处理后,可接近实时发送

注意

如果您选择通过 S2S 集成之一发送订阅事件,大多数客户仍应集成 Singular SDK 来管理会话和非订阅事件。

在应用程序中实施订阅状态管理

通过集成 Google 的 Play Billing Library 和 Apple 的 StoreKit,您可以直接在设备上查询订阅信息并管理订阅状态。这种设置允许与 Singular 的一种实现方法集成。下面的示例代码片段演示了计费库和 StoreKit 的简单实现,可作为实用范例。您应根据自己应用程序的代码和订阅模式修改这些示例。

安卓:集成 Google Play 计费库

1.将计费库添加到项目中

在 build.gradle 中添加 Google Play 计费库配置

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

2.设置应用内产品和订阅

Google Play 控制台中配置应用内产品和订阅项目

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 框架集成到您的 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 发送订阅事件

当上述实现中的订阅状态发生变化时,应向Singular发送新的自定义收入事件。请勿使用 IAP 功能,也请勿向 Singular 发送收据值。请按照您在应用程序中实施的 Singular SDK 的相应实施指南,发送不含收据的 customRevenue() 事件。

  • iOS SDK:使用该方法发送 "订阅 "事件名称:

    (void)customRevenue:(NSString*)eventname currency:(NSString *)currency
            amount:(double)amount withAttributes:(NSDictionary*)attributes;
  • Android SDK:使用此方法发送 "订阅 "事件名称:

    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:使用此方法发送 "订阅 "事件名称:

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

发送订阅事件 S2S

如果您希望实时发送订阅事件,并在后端管理订阅事件,可以向 Singular 的 REST API 发送事件。

使用事件端点向 Singular 发送订阅事件,并确保包含收入参数

  • 如果您已经实施了 Singular SDK:
    • 不应使用此选项从 SDK 发送订阅事件
    • 无需与启动(会话)S2S 端点集成

通过 3P 集成发送订阅事件

如果使用第三方服务管理订阅,这些供应商会通过自己的集成方法获取订阅数据。然后,它们会将订阅事件发送到已集成到其系统中的 Singular REST API。这些集成需要在合作伙伴平台中进行一些配置,请参阅以下各自的指南:

订阅事件

可以向 Singular 发送几种不同的订阅事件。请注意,Singular 的标准事件名称在下文中提供(参见相关 SDK 文档),但如果需要,也可以使用自定义事件名称。

订阅状态 事件 SDK 方法 S2S 集成
订阅 sng_subscribe
  • 自定义收入事件方法(不支持收据验证)
  • 带有收入参数的 Evt 请求
试用开始 sng_start_trial
  • 事件方法(无收入金额)
  • 标准 evt 请求
试用结束 sng_end_trial (尚未正式成为标准事件,因此将作为自定义事件发送)
  • 事件方法(无收入金额)
  • 标准事件请求
退款 subscription_refunded
  • 带有负收入的自定义收入事件方法(可选)
  • 事件方法(无收入金额)
  • 带收入参数和负值的事件请求(可选)
  • 标准事件请求
取消 取消订阅
  • 事件方法(无收入金额)
  • 标准 evt 请求
续订 subscription_renewed
  • 自定义收入事件方法(不支持收据验证)
  • 带有收入参数的 evt 请求

注意

如果选择通过 customRevenue 方法发送订阅事件,请确保只发送isRestored 为 false 的事件。

SKAN 测量注意事项

Singular 可以通过上述所有集成方法测量订阅事件数据。请注意,根据 SKAN 版本的不同,事件测量可能会受到 SKAN 回传测量窗口的限制。

如果您计划为生命周期事件实施 Singular SDK,并使用上述 S2S 集成方法之一发送订阅事件,请联系您的 CSM 以启用混合 SKAN。