概述:
本文档全面介绍了如何使用 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 计费库配置
2.设置应用内产品和订阅
在Google Play 控制台中配置应用内产品和订阅项目
3.查询订阅信息
使用 BillingClient 在应用程序中查询购买历史和订阅状态。
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()
}
BillingClient billingClient = BillingClient.newBuilder(context)
.setListener(purchaseUpdateListener)
.enablePendingPurchases()
.build();
BillingClientStateListener billingClientStateListener = new BillingClientStateListener() {
@Override
public void onBillingSetupFinished(BillingResult billingResult) {
if (billingResult.getResponseCode() == BillingClient.BillingResponseCode.OK) {
// The billing client is ready, you can now query subscription information asynchronously
billingClient.queryPurchasesAsync(BillingClient.SkuType.SUBS, (result, purchasesList) -> {
if (result.getResponseCode() == BillingClient.BillingResponseCode.OK && purchasesList != null) {
// Handle the retrieved subscription list
for (Purchase purchase : purchasesList) {
// Process each subscription purchase
}
} else {
// Handle error in queryPurchasesAsync
}
});
} else {
// Handle error on setup finished
}
}
@Override
public void onBillingServiceDisconnected() {
// Retry connection after a delay if the service gets disconnected
new Handler(Looper.getMainLooper()).postDelayed(() -> billingClient.startConnection(billingClientStateListener), 3000);
}
};
billingClient.startConnection(billingClientStateListener);
@Override
protected void onDestroy() {
super.onDestroy();
if (billingClient != null) {
billingClient.endConnection();
}
}
iOS:集成 StoreKit
1.实施 StoreKit
将 StoreKit 框架集成到您的 iOS 应用程序中。
2.设置应用内产品和订阅
在App Store Connect中设置应用内产品和订阅项目
3.查询订阅信息
使用 SKPaymentQueue 和 SKReceiptRefreshRequest 获取订阅状态和收据信息。
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 |
|
|
试用开始 | sng_start_trial |
|
|
试用结束 | sng_end_trial (尚未正式成为标准事件,因此将作为自定义事件发送) |
|
|
退款 | subscription_refunded |
|
|
取消 | 取消订阅 |
|
|
续订 | subscription_renewed |
|
|
注意
如果选择通过 customRevenue 方法发送订阅事件,请确保只发送isRestored 为 false 的事件。SKAN 测量注意事项
Singular 可以通过上述所有集成方法测量订阅事件数据。请注意,根据 SKAN 版本的不同,事件测量可能会受到 SKAN 回传测量窗口的限制。
如果您计划为生命周期事件实施 Singular SDK,并使用上述 S2S 集成方法之一发送订阅事件,请联系您的 CSM 以启用混合 SKAN。