Basic methods
Please take a look at our Expert tips before integrating the events.
Real Payment
To track payments in a real currency, dispatch this event right after the system validates that the payment went through successfully. The event is fundamental and mandatory for all the app metrics related to monetization.
DTDAnalytics.realCurrencyPayment(orderId: "Order ID",
price: 12.5,
productId: "Product ID",
currencyCode: "USD")
orderId
string
from 1 to 65 symbols
A unique transaction ID. Use transactionIdentifier
property value in SKPaymentTransaction
object in a complete transaction receipt.
currencyCode
string
precisely 3 symbols
price
double
from Double.min to Double.max
The item price in the transaction currency.
productId
string
from 1 to 255 symbols
Item name. We recommend using a bundle or names in the same language.
[DTDAnalytics realCurrencyPaymentWithOrderId:@"Order ID"
price:12.5
productId:@"Product ID"
currencyCode:@"USD"];
orderId
NSString
from 1 to 65 symbols
A unique transaction ID. Use transactionIdentifier
property value in SKPaymentTransaction
object in a complete transaction receipt.
currencyCode
NSString
precisely 3 symbols
price
double
from Double.min to Double.max
The item price in the transaction currency.
productId
NSString
from 1 to 255 symbols
Item name. We recommend using a bundle or names in the same language.
DTDAnalytics.realCurrencyPayment(
orderId = "Order ID",
price = 12.5,
productId = "Product ID",
currencyCode = "USD"
)
orderId
string
from 1 to 65 symbols
A unique transaction ID.
currencyCode
string
precisely 3 symbols
price
double
from Double.min to Double.max
The item price in the transaction currency.
productId
string
from 1 to 255 symbols
Item name. We recommend using a bundle or names in the same language.
How to find the transaction ID in GooglePlay transaction?
Find the INAPP_PURCHASE_DATA object In the JSON fields that are returned in the response data for a purchase order. A unique transaction identifier is the value of orderId property in INAPP_PURCHASE_DATA object. If the order is a test purchase made via the In-app Billing Sandbox, orderId property will be empty.
DTDAnalytics.INSTANCE.realCurrencyPayment(
"Order ID",
12.5,
"Product ID",
"USD"
);
orderId
string
from 1 to 65 symbols
A unique transaction ID.
currencyCode
string
precisely 3 symbols
price
double
from Double.min to Double.max
The item price in the transaction currency.
productId
string
from 1 to 255 symbols
Item name. We recommend using a bundle or names in the same language.
How to find the transaction ID in GooglePlay transaction?
Find the INAPP_PURCHASE_DATA object In the JSON fields that are returned in the response data for a purchase order. A unique transaction identifier is the value of orderId property in INAPP_PURCHASE_DATA object. If the order is a test purchase made via the In-app Billing Sandbox, orderId property will be empty.
DTDAnalytics.RealCurrencyPayment(
orderId: "Order ID",
price: 12.5,
productId: "Product ID",
currencyCode: "USD");
orderId
string
from 1 to 65 symbols
A unique transaction ID.
currencyCode
string
precisely 3 symbols
price
double
from double.MinValue to double.MaxValue
The item price in the transaction currency.
productId
string
from 1 to 255 symbols
Item name. We recommend using a bundle or names in the same language.
DTDAnalytics.RealCurrencyPayment(
orderId: "Order ID",
price: 12.5,
productId: "Product ID",
currencyCode: "USD");
orderId
string
from 1 to 65 symbols
A unique transaction ID.
currencyCode
string
precisely 3 symbols
price
double
from Double.MinValue to Double.MaxValue
The item price in the transaction currency.
productId
string
from 1 to 255 symbols
Item name. We recommend using a bundle or names in the same language.
window.devtodev.realCurrencyPayment(
orderId,
price,
productId,
currencyCode)
orderId
string
from 1 to 65 symbols
A unique transaction ID.
currencyCode
string
precisely 3 symbols
price
double
from Number.MIN_VALUE to Number.MAX_VALUE
The item price in the transaction currency.
productId
string
from 1 to 255 symbols
Item name. We recommend using a bundle or names in the same language.
orderId
FString
from 1 to 65 symbols
A unique transaction ID.
currencyCode
FString
precisely 3 symbols
price
float
from float.MinValue to float.MaxValue
The item price in the transaction currency.
productId
FString
from 1 to 255 symbols
Item name. We recommend using a bundle or names in the same language.
1UDTDAnalyticsBPLibrary::RealCurrencyPayment("OrderId", 12.5, "ProductId", "USD");
DTDAnalytics.RealCurrencyPayment("orderId", 9.99, "productId", "USD")
orderId
String
from 1 to 65 symbols
A unique transaction ID.
currencyCode
String
precisely 3 symbols
price
Float
from Double.min to Double.max
The item price in the transaction currency.
productId
String
from 1 to 255 symbols
Item name. We recommend using a bundle or names in the same language.
By default (easy to change in the appโs settings) devtodev server invalidates transactions with previously-used identifiers. Besides, the server performs identifier checks by its outer appearance in order to avoid obvious fraud.
If you want to exclude fraud payments from your reports altogether, before creating โReal Currency Paymentโ event, use devtodev anti-cheat feature.
Custom Events
If you want to track non-basic events, you can create custom events of your own. How you are going to apply them, depends solely on you.
Attention! We strongly recommend that you do not use custom event properties to transfer and store data that fits the definition of personal data!
DTDAnalytics.customEvent(eventName: "Event name")
If you want to pass custom parameters, use DTDCustomEventParameters
class instance.
let parameters = DTDCustomEventParameters()
parameters.add(key: "key for string value", value: "string value")
parameters.add(key: "key for int value", value: 10)
parameters.add(key: "key for bool value", value: true)
parameters.add(key: "key for double value", value: 12.5)
DTDAnalytics.customEvent(eventName: "Event name", parameters: parameters)
eventName
string
from 1 to 72 symbols
Custom event name.
parameters
DTDCustomEventParameters
key - from 1 to 32 symbols
value - see below
Custom event parameters.
The following data types can be passed using the DTDCustomEventParameters
object:
int
from Int64.min to Int64.max
string
from 1 to 255 symbols
bool
true/false
double
from Double.min to Double.max
[DTDAnalytics customEvent:@"Event name"];
If you want to pass custom parameters, use DTDCustomEventParameters
class instance.
DTDCustomEventParameters *parameters = [[DTDCustomEventParameters alloc] init];
[parameters addString:@"key for string value" value:@"string value"];
[parameters addInt:@"key for int value" value:10];
[parameters addBool:@"key for bool value" value:true];
[parameters addDouble:@"key for double value" value:12.5];
[DTDAnalytics customEvent:@"Event name" withParameters:parameters];
eventName
NSString
from 1 to 72 symbols
Custom event name.
parameters
DTDCustomEventParameters
key - from 1 to 32 symbols
value - see below
Custom event parameters.
The following data types can be passed using the DTDCustomEventParameters
object:
int
from Int64.min to Int64.max
string
from 1 to 255 symbols
bool
true/false
double
from Double.min to Double.max
DTDAnalytics.customEvent(eventName = "Event name")
If you want to pass custom parameters, use DTDCustomEventParameters
class instance.
let parameters = DTDCustomEventParameters()
parameters.add(key = "key for string value", value = "string value")
parameters.add(key = "key for int value", value = 10)
parameters.add(key = "key for bool value", value = true)
parameters.add(key = "key for double value", value = 12.5)
DTDAnalytics.customEvent(
eventName = "Event name",
customEventParameters = parameters
)
eventName
string
from 1 to 72 symbols
Custom event name.
parameters
DTDCustomEventParameters
key - from 1 to 32 symbols
value - see below
Custom event parameters.
The following data types can be passed using the DTDCustomEventParameters
object:
Long
from Long.min to Long.max
String
from 1 to 255 symbols
Boolean
true/false
Double
from Double.min to Double.max
DTDAnalytics.INSTANCE.customEvent("Event name");
If you want to pass custom parameters, use DTDCustomEventParameters
class instance.
DTDCustomEventParameters parameters = new DTDCustomEventParameters();
parameters.add("key for string value", "string value");
parameters.add("key for int value", 10);
parameters.add("key for bool value", true);
parameters.add("key for double value", 12.5);
DTDAnalytics.INSTANCE.customEvent("Event name", parameters);
eventName
string
from 1 to 72 symbols
Custom event name.
parameters
DTDCustomEventParameters
key - from 1 to 32 symbols
value - see below
Custom event parameters.
The following data types can be passed using the DTDCustomEventParameters
object:
Long
from Long.min to Long.max
String
from 1 to 255 symbols
Boolean
true/false
Double
from Double.min to Double.max
DTDAnalytics.CustomEvent(eventName: "Event name");
If you want to pass custom parameters, use DTDCustomEventParameters
class instance.
var parameters = new DTDCustomEventParameters();
parameters.Add(key: "key for string value", value: "string value");
parameters.Add(key: "key for int value", value: 10);
parameters.Add(key: "key for bool value", value: true);
parameters.Add(key: "key for double value", value: 12.5);
DTDAnalytics.CustomEvent(eventName: "Event name", parameters: parameters);
eventName
string
from 1 to 72 symbols
Custom event name.
parameters
DTDCustomEventParameters
key - from 1 to 32 symbols
value - see below
Custom event parameters.
The following data types can be passed using the DTDCustomEventParameters
object:
long
from long.MinValue to long.MaxValue
string
from 1 to 255 symbols
bool
true/false
double
from double.MinValue to double.MaxValue
DTDAnalytics.CustomEvent(eventName: "Event name");
If you want to pass custom parameters, use DTDCustomEventParameters
class instance.
var parameters = new DTDCustomEventParameters();
parameters.Add(key: "key for string value", value: "string value");
parameters.Add(key: "key for int value", value: 10);
parameters.Add(key: "key for bool value", value: true);
parameters.Add(key: "key for double value", value: 12.5);
DTDAnalytics.CustomEvent(eventName: "Event name", parameters: parameters);
eventName
string
from 1 to 72 symbols
Custom event name.
parameters
DTDCustomEventParameters
key - from 1 to 32 symbols
value - see below
Custom event parameters.
The following data types can be passed using the DTDCustomEventParameters
object:
long
from Int64.MinValue to Int64.MaxValue
string
from 1 to 255 symbols
bool
true/false
double
from Double.MinValue to Double.MaxValue
window.devtodev.customEvent(eventName, parameters)
If you want to pass custom parameters, use an object with parameters.
window.devtodev.customEvent("Event name", {
"key for string value" : "string value",
"key for int value": 10,
"key for bool value": true,
"key for double value": 12.5
})
eventName
string
from 1 to 72 symbols
Custom event name.
parameters
object
key - from 1 to 32 symbols
value - see below
Custom event parameters.
The following data types can be passed using parameters object:
long
from Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER
string
from 1 to 255 symbols
bool
true/false
double
from Number.MIN_VALUE to Number.MAX_VALUE
eventName
FString
from 1 to 72 symbols
Custom event name.
UDTDAnalyticsBPLibrary::CustomEvent("EventName");
If you want to pass custom parameters, use:
eventName
FString
from 1 to 72 symbols
Custom event name.
parameters
FDTDCustomEventParams
StringParameters (TMap<FString, FString>)
IntParameters (TMap<FString, int64>)
FloatParameters (TMap<FString, float>)
BoolParameters (TMap<FString, bool>)
key - from 1 to 32 symbols
value - see below
Custom event parameters.
Warning: avoid duplicate keys in all dictionaries. Because dictionaries are combined into a generic dictionary [string: any] in native code.
The following data types can be passed using the DTDCustomEventParameters object:
int64
from int64.MinValue to int64.MaxValue
FString
from 1 to 255 symbols
bool
true/false
float
from float.MinValue to float.MaxValue
FDTDCustomEventParams params;
params.BoolParameters.Add("BoolKey", true);
params.FloatParameters.Add("FloatKey", 3.3);
params.IntParameters.Add("IntKey");
params.StringParameters.Add("StringKey", "StringValue");
UDTDAnalyticsBPLibrary::CustomEventWithParams("EventName", params);
DTDAnalytics.CustomEvent("CustomEvent")
If you want to pass custom parameters, use GDDTDCustomEventParameters
class instance.
var parameters = GDDTDCustomEventParams.new()
parameters.AddStringValue("str_key", "str_value")
parameters.AddBoolValue("bool_key", true)
parameters.AddIntegerValue("int_key", 100)
parameters.AddFloatValue("float_key", 0.0015)
DTDAnalytics.CustomEventWithParams("CustomEventWithParams", parameters)
eventName
string
from 1 to 72 symbols
Custom event name.
parameters
GDDTDCustomEventParams
key - from 1 to 32 symbols
value - see below
Custom event parameters.
The following data types can be passed using the GDDTDCustomEventParameters
object:
int
from Int64.min to Int64.max
String
from 1 to 255 symbols
bool
true/false
Float
from Float.min to Float.max
devtodev supports no more than 300 custom event names in a single project. Events that exceed the limit of custom event names will be discarded. Try to integrate the tracked actions by type to the event name level, and move the characteristic tags in the parameters.
For example, if you need to track purchasing โPaperโ and โPenโ items, then you donโt need to create two events with the names โPaper Purchaseโ and โPen Purchaseโ. Create a โPurchaseโ event and add an โItemโ parameter to it with the appropriate โPaperโ or โPenโ value. This way, you can use just one event to track many items.
For a string parameter, you can use no more than 50,000 unique values โโfor the entire history of events. If the number of unique values exceeds the limit, the parameter gets locked by the system and gets discarded from the received data. Therefore, we donโt recommend using highly variable parameters like user IDs or time as string values โโ(moreover, they are automatically added to the event).
We strongly recommend that you do not change the data type passed in the same parameter. If you change the data type in a parameter, it will be duplicated with the same name, which may cause issues while processing reports.
Subscriptions
The described method is available beginning with version 2.1.0!
Tracking of subscriptions is now available for Apple App Store and Google Play only.
Please note that in order to track subscriptions, you need to do the following:
Call the
subscriptionPayment
method (described below)
To track your income from subscriptions, you need to call the following method at the moment of the subscription purchase even if the user signed up for a trial subscription: func subscriptionPayment(transaction: SKPaymentTransaction, product: SKProduct).
For example:
extension Purchases: SKPaymentTransactionObserver {
func paymentQueue(_ queue: SKPaymentQueue, updatedTransactions transactions: [SKPaymentTransaction]) {
for transaction in transactions {
switch transaction.transactionState {
case .purchased:
// Your code ...
if let product = products?[transaction.payment.productIdentifier] {
DTDAnalytics.subscriptionPayment(transaction: transaction, product: product)
}
case .restored:
// Your code ...
case .failed:
// Your code ...
default:
// Your code ...
}
}
}
}
Further user actions - renewal, unsubscription, etc. are tracked by using the data received from AppStore in the server-server format. You will need the corresponding setting for it.
Also, if you want to track changes in the status of the subscriptions purchased before devtodev SDK 2.0 integration, you need to transfer your history of previously purchased subscriptions to devtodev.
The SDK monitors the need for historical data to avoid sending out excessive queries to App Store. Use the DTDAnalytics.isRestoreTransactionHistoryRequired
method to check whether or not there is a need in sending out the information about the previously purchased subscriptions to devtodev. The method returns BOOL value.
An example of a purchase history query with verification of the need for it:
DTDAnalytics.isRestoreTransactionHistoryRequired { isNeedRestore in
if isNeedRestore {
DispatchQueue.main.async {
SKPaymentQueue.default().restoreCompletedTransactions()
}
}
}
Use the DTDAnalytics.subscriptionHistory
method to transfer the list of previously purchased subscriptions received from App Store.
If your project accounts users by user ID (not by device ID) and the device is used by more than one user, you need to filter the transaction history so that it will contain only those transactions that belong to the active user. Otherwise, subscriptions of all device users will be attributed to the user who was the first to launch the app after the integration of subscription tracking.
extension Purchases: SKPaymentTransactionObserver {
func paymentQueueRestoreCompletedTransactionsFinished(_ queue: SKPaymentQueue) {
// Your code ...
let restoredTransactions = queue.transactions.filter { $0.transactionState == .restored }
DTDAnalytics.subscriptionHistory(transactions: restoredTransactions)
}
}
To recover the purchase history, the user should be logged in with his Apple ID. Be mindful of this before starting the recovering process.
Please note that in order to track subscriptions, you need to do the following:
Call the
subscriptionPayment
method (described below)
To track your income from subscriptions, you need to call the following method at the moment of the subscription purchase even if the user signed up for a trial subscription: func subscriptionPayment(transaction: Transaction, product: Product).
For example:
func purchase(_ product: Product) async throws {
let result = try await product.purchase()
switch result {
case let .success(.verified(transaction)):
// Successful purchase
await transaction.finish()
DTDAnalytics.subscriptionPayment(transaction: transaction, product: product)
case let .success(.unverified(_, error)):
// Successful purchase but transaction/receipt can't be verified
// Could be a jailbroken phone
print(error)
case .pending:
// Transaction waiting on SCA (Strong Customer Authentication) or
// approval from Ask to Buy
break
case .userCancelled:
// Do nothing
break
@unknown default:
break
}
}
Fork with Transaction.updates:
private func listenForTransactions() -> Task<Void, Error> {
return Task.detached {
// Iterate through any transactions that don't come from a direct call to `purchase()`.
for await verificationResult in Transaction.updates {
guard let case .verified(let transaction) = verificationResult else { return }
if let revocationDate = transaction.revocationDate {
// Remove access to the product identified by transaction.productID.
// Transaction.revocationReason provides details about
// the revoked transaction.
} else if let expirationDate = transaction.expirationDate,
expirationDate < Date() {
// Do nothing, this subscription is expired.
return
} else if transaction.isUpgraded {
// Do nothing, there is an active transaction
// for a higher level of service.
return
} else {
// Provide access to the product identified by
// transaction.productID.
if let product = self.products.first(where: { $0.id == transaction.productID }) {
DTDAnalytics.subscriptionPayment(transaction: transaction, product: product)
}
}
}
}
}
Further user actions - renewal, unsubscription, etc. are tracked by using the data received from AppStore in the server-server format. You will need the corresponding setting for it.
Also, if you want to track changes in the status of the subscriptions purchased before devtodev SDK 2.0 integration, you need to transfer your history of previously purchased subscriptions to devtodev.
The SDK monitors the need for historical data to avoid sending out excessive queries to App Store. Use the DTDAnalytics.isRestoreTransactionHistoryRequired
method to check whether or not there is a need in sending out the information about the previously purchased subscriptions to devtodev. The method returns BOOL value.
An example of a purchase history query with verification of the need for it:
DTDAnalytics.isRestoreTransactionHistoryRequired { [weak self] flag in
if flag {
Task {
await self?.restoreTransactions()
}
}
}
Use the DTDAnalytics.subscriptionHistory
method to transfer the list of previously purchased subscriptions received from App Store.
If your project accounts users by user ID (not by device ID) and the device is used by more than one user, you need to filter the transaction history so that it will contain only those transactions that belong to the active user. Otherwise, subscriptions of all device users will be attributed to the user who was the first to launch the app after the integration of subscription tracking.
extension Purchases: SKPaymentTransactionObserver {
func restoreTransactions() async {
var transactions: [Transaction] = []
for await transaction in Transaction.all {
if case let .verified(verifiedTransaction) = transaction {
transactions.append(verifiedTransaction)
}
}
DTDAnalytics.subscriptionHistory(transactions: transactions)
}
To recover the purchase history, the user should be logged in with his Apple ID. Be mindful of this before starting the recovering process.
Please note that in order to track subscriptions, you need to do the following:
Call the
subscriptionPayment
method (described below)
To track your income from subscriptions, you need to call the following method at the moment of the subscription purchase even if the user signed up for a trial subscription:
(void)subscriptionPaymentWithTransaction:(SKPaymentTransaction * _Nonnull)transaction product:(SKProduct * _Nonnull)product;
For example:
- (void)paymentQueue:(SKPaymentQueue *)queue updatedTransactions:(NSArray *)transactions{
for(SKPaymentTransaction *transaction in transactions) {
switch(transaction.transactionState){
case SKPaymentTransactionStatePurchasing: {
// Your code ...
break;
}
case SKPaymentTransactionStatePurchased: {
// Your code ...
SKProduct *product = [_products objectForKey:transaction.payment.productIdentifier];
if (product != nil) {
[DTDAnalytics subscriptionPaymentWithTransaction:transaction product:product];
}
break;
}
case SKPaymentTransactionStateRestored: {
// Your code ...
break;
}
case SKPaymentTransactionStateFailed: {
// Your code ...
break;
}
case SKPaymentTransactionStateDeferred: {
// Your code ...
break;
}
}
}
}
Further user actions - renewal, unsubscription, etc. are tracked by using the data received from AppStore in the server-server format. You will need the corresponding setting for it.
Also, if you want to track changes in the status of the subscriptions purchased before devtodev SDK 2.0 integration, you need to transfer your history of previously purchased subscriptions to devtodev.
The SDK monitors the need for historical data to avoid sending out excessive queries to App Store. Use the (void)isRestoreTransactionHistoryRequiredWithCompletionHandler:( void (^ _Nonnull)(BOOL))completionHandler;
method to check whether or not there is a need in sending out the information about the previously purchased subscriptions to devtodev. The method returns BOOL value.
An example of a purchase history query with verification of the need for it:
[DTDAnalytics isRestoreTransactionHistoryRequiredWithCompletionHandler:^(BOOL isNeedRestore){
if (isNeedRestore == true) {
dispatch_async(dispatch_get_main_queue(), ^{
[SKPaymentQueue.defaultQueue restoreCompletedTransactions];
});
}
}];
Use the (void)subscriptionHistoryWithTransactions:(NSArray<SKPaymentTransaction *> * _Nonnull)transactions;
method to transfer the list of previously purchased subscriptions received from App Store.
If your project accounts users by user ID (not by device ID) and the device is used by more than one user, you need to filter the transaction history so that it will contain only those transactions that belong to the active user. Otherwise, subscriptions of all device users will be attributed to the user who was the first to launch the app after the integration of subscription tracking.
-(void)paymentQueueRestoreCompletedTransactionsFinished:(SKPaymentQueue *)queue {
NSMutableArray *restoredTransactions = [NSMutableArray new];
for (SKPaymentTransaction *transaction in queue.transactions) {
if (transaction.transactionState == SKPaymentTransactionStateRestored) {
[restoredTransactions addObject:transaction];
}
}
[DTDAnalytics subscriptionHistoryWithTransactions:restoredTransactions];
}
To recover the purchase history, the user should be logged in with his Apple ID. Be mindful of this before starting the recovering process.
Please note that in order to track subscriptions, you need to do the following:
Call the
subscriptionPayment
method (described below)
Before sending a request for subscription from your app, during the creation of BillingFlowParams
, to the setObfuscatedAccountId
function of the BillingFlowParams.newBuilder()
object insert obfuscatedAccountId
obtained from DTDAnalytics.getObfuscatedAccountId
.
Attention! The obfuscated identifier is returned asynchronously, outside of the calling thread!
Example:
DTDAnalytics.getObfuscatedAccountId { obfuscatedAccountId ->
val flowParams: BillingFlowParams = BillingFlowParams.newBuilder()
.setObfuscatedAccountId(obfuscatedAccountId)
.build()
val result = billingClient.launchBillingFlow(activity, flowParams)
}
To track your subscriptions, add this event immediately after the platform confirms that the subscription was approved by the user.
DTDAnalytics.subscriptionPayment(orderId: String,
price: Double,
productId: String,
currencyCode: String);
Parameter
Type
Restrictions
Description
orderId
string
from 1 to 65 symbols
A unique transaction identifier.
currencyCode
string
precisely 3 symbols
price
double
from Double.min to Double.max
The item price in the transaction currency.
productId
string
from 1 to 255 symbols
Item name. We recommend using a bundle or names in the same language.
How to find the transaction ID in GooglePlay transaction?
Find the INAPP_PURCHASE_DATA object In the JSON fields that are returned in the response data for a purchase order. A unique transaction identifier is the value of orderId property in INAPP_PURCHASE_DATA object. If the order is a test purchase made via the In-app Billing Sandbox, orderId property will be empty.
Further user actions - renewal, unsubscription, etc. are tracked by using the data received from Google Play in the server-server format. You will need the corresponding setting for it.
The subscriptionHistory
method is used for matching users with subscribers who purchased their subscriptions before the SDK 2.0 integration. Otherwise, it will be impossible to establish the affiliation when it gets renewed or cancelled.
To get a list of active subscriptions call billingClient.queryPurchasesAsync
. After successfully receiving a response from Google Play Services, pass it to DTDAnalytics.subscriptionHistory(purchaseList: List<String>).
purchaseList: List<String> purchaseList
- a string containing list of json objects is passed to the DTDAnalytics.subscriptionHistory
method. For the event to run, the json object must contain the following keys:
orderID
- a unique transaction identifierproductID
- a unique product identifier
The SDK monitors the need for historical data to avoid sending out excessive queries. Use the DTDAnalytics.isRestoreTransactionHistoryRequired
method to check whether or not there is a need in sending out the information about the previously purchased subscriptions to devtodev. The method returns a Boolean value.
Attention! DTDAnalytics.isRestoreTransactionHistoryRequired
is returned asynchronously, outside of the calling thread!
Example:
DTDAnalytics.isRestoreTransactionHistoryRequired { isNeedRestore ->
if(isNeedRestore) {
billingClient.queryPurchasesAsync(BillingClient.SkuType.SUBS) { billingResult, purchaseList ->
if (billingResult.responseCode == BillingClient.BillingResponseCode.OK) {
val purchases = mutableListOf<String>()
purchaseList.forEach { purchase -> purchases.add(purchase.originalJson) }
DTDAnalytics.subscriptionHistory(purchases)
}
}
}
}
If your project accounts users by user ID (not by device ID) and the device is used by more than one user, you need to filter the transaction history so that it will contain only those transactions that belong to the active user. Otherwise, subscriptions of all device users will be attributed to the user who was the first to launch the app after the integration of subscription tracking.
Please note that in order to track subscriptions, you need to do the following:
Call the
subscriptionPayment
method (described below)
Before sending a request for subscription from your app, during the creation of BillingFlowParams
, to the setObfuscatedAccountId
function of the BillingFlowParams.newBuilder()
object insert obfuscatedAccountId
obtained from DTDAnalytics.INSTANCE.getObfuscatedAccountId.
Attention! The obfuscated identifier is returned asynchronously, outside of the calling thread!
Example:
DTDAnalytics.INSTANCE.getObfuscatedAccountId(obfuscatedAccountId -> {
BillingFlowParams flowParams = BillingFlowParams.newBuilder()
.setObfuscatedAccountId(obfuscatedAccountId)
.build();
billingClient.launchBillingFlow(activity, flowParams);
return null;
}
);
To track your subscriptions, add this event immediately after the platform confirms that the subscription was approved by the user.
DTDAnalytics.INSTANCE.subscriptionPayment(orderId: String, price: Double, productId: String, currencyCode: String);
Parameter
Type
Restrictions
Description
orderId
string
from 1 to 65 symbols
A unique transaction identifier.
currencyCode
string
precisely 3 symbols
price
double
from Double.min to Double.max
The item price in the transaction currency.
productId
string
from 1 to 255 symbols
Item name. We recommend using a bundle or names in the same language.
How to find the transaction ID in GooglePlay transaction?
Find the INAPP_PURCHASE_DATA object In the JSON fields that are returned in the response data for a purchase order. A unique transaction identifier is the value of orderId property in INAPP_PURCHASE_DATA object. If the order is a test purchase made via the In-app Billing Sandbox, orderId property will be empty.
Further user actions - renewal, unsubscription, etc. are tracked by using the data received from Google Play in the server-server format. You will need the corresponding setting for it.
The subscriptionHistory
method is used for matching users with subscribers who purchased their subscriptions before the SDK 2.0 integration. Otherwise, it will be impossible to establish the affiliation when it gets renewed or cancelled.
To get a list of active subscriptions call billingClient.queryPurchasesAsync
. After successfully receiving a response from Google Play Services, pass it to DTDAnalytics.subscriptionHistory(purchaseList: List<String>).
purchaseList: List<String> purchaseList
- a string containing list of json objects is passed to the DTDAnalytics.INSTANCE.subscriptionHistory
method. For the event to run, the json object must contain the following keys:
orderID
- a unique transaction identifierproductID
- a unique product identifier
The SDK monitors the need for historical data to avoid sending out excessive queries. Use the DTDAnalytics.INSTANCE.isRestoreTransactionHistoryRequired
method to check whether or not there is a need in sending out the information about the previously purchased subscriptions to devtodev. The method returns a Boolean value.
Attention! DTDAnalytics.INSTANCE.isRestoreTransactionHistoryRequired
is returned asynchronously, outside of the calling thread!
Example:
DTDAnalytics.INSTANCE.isRestoreTransactionHistoryRequired(isNeedRestore -> {
if (isNeedRestore) {
billingClient.queryPurchasesAsync(BillingClient.ProductType.SUBS, (billingResult, purchaseList) -> {
if (billingResult.getResponseCode() == BillingClient.BillingResponseCode.OK) {
ArrayList<String> purchases = new ArrayList<>();
purchaseList.forEach(purchase ->
purchases.add(purchase.getOriginalJson())
);
DTDAnalytics.INSTANCE.subscriptionHistory(purchases);
}
});
}
return null;
});
If your project accounts users by user ID (not by device ID) and the device is used by more than one user, you need to filter the transaction history so that it will contain only those transactions that belong to the active user. Otherwise, subscriptions of all device users will be attributed to the user who was the first to launch the app after the integration of subscription tracking.
In order to work with Unity subscriptions, you need to integrate the subscription module to your project. You can do it by manually importing the unitypackage.
Integration by importing the unitypackage
Download the latest version of devtodev package from the repository: https://github.com/devtodev-analytics/Unity-sdk-3.0/releases/latest
Import DTDAnalytics.unitypackage to your project
Import DTDSubscriptions.unitypackage to your project.
For the DTDSubscriptions
module to function you need the DTDAnalytics
and Unity IAP modules.
You also need to create an AppleTangle
file (only for iOS). Open the Unity editor menu and choose Window โ Unity IAP โ Receipt Validation Obfuscator (pic. 1).
In case you donโt use the IAP receipt validation, clear the input field under โ2. Paste the key here:โ and click Obfuscate Google Play Licence Key (pic. 2).
Initialize the
DTDAnalytics
module (see our instruction manual).Add
DTDSubscriptions.Initialize(IStoreController controller)
to the OnInitialized method.
/// <summary>
/// Your IStoreListener implementation of OnInitialized.
/// </summary>
public void OnInitialized(IStoreController controller, IExtensionProvider extensions)
{
DTDSubscriptions.Initialize(controller);
}
Restore purchase history in order for the module to function correctly.
If you use Google Play, after successful IAP initialization call the
DTDSubscriptions.History()
method.
To avoid excessive restoring of subscription history, use the DTDSubscriptions.IsRestoreTransactionHistoryRequired(Action<bool> resultCallback)
method. If the resultCallback returns true, call the DTDSubscriptions.History()
method.
Example:
public void OnInitialized(IStoreController controller, IExtensionProvider extensions)
{
#if UNITY_ANDROID
DTDSubscriptions.Initialize(controller);
DTDSubscriptions.IsRestoreTransactionHistoryRequired((b) =>
{
if(b) DTDSubscriptions.History();
});
#endif
}
If you use Apple App Store, first set the
DTDSubscriptions.IsRestoring
property to true (this will filter out unwanted transactions). After restoring IAP transactions, call theDTDSubscriptions.History()
method. After that, set theDTDSubscriptions.IsRestoring propert
y to false.
Example:
public void OnInitialized(IStoreController controller, IExtensionProvider extensions)
{
DTDSubscriptions.Initialize(controller);
if UNITY_STANDALONE_OSX || UNITY_IOS
DTDSubscriptions.IsRestoring = true;
extensions.GetExtension<IAppleExtensions>().RestoreTransactions(result =>
{
if (result)
{
DTDSubscriptions.IsRestoreTransactionHistoryRequired((b) =>
{
if (b) DTDSubscriptions.History();
});
}
DTDSubscriptions.IsRestoring = false;
});
#endif
}
Add a
DTDSubscriptions.Payment(Product product)
call to theProcessPurchase
method.
public PurchaseProcessingResult ProcessPurchase (PurchaseEventArgs e)
{
var product = e.purchasedProduct;
DTDSubscriptions.Payment(product);
return PurchaseProcessingResult.Complete;
}
Below you can see an example of the entire script:
using DevToDev.Subscriptions;
using UnityEngine;
using UnityEngine.Purchasing;
public class MyIAPManager : IStoreListener
{
public IStoreController StoreController { get; private set; }
public void InitializeIAPManager()
{
var builder = ConfigurationBuilder.Instance(StandardPurchasingModule.Instance());
builder.AddProduct("example", ProductType.Subscription);
UnityPurchasing.Initialize(this, builder);
}
/// <summary>
/// Called when Unity IAP is ready to make purchases.
/// </summary>
public void OnInitialized(IStoreController controller, IExtensionProvider extensions)
{
StoreController = controller;
DTDSubscriptions.Initialize(controller);
#if UNITY_ANDROID
DTDSubscriptions.IsRestoreTransactionHistoryRequired((b) =>
{
if (b) DTDSubscriptions.History();
});
#elif UNITY_STANDALONE_OSX || UNITY_IOS
DTDSubscriptions.IsRestoring = true;
extensions.GetExtension<IAppleExtensions>().RestoreTransactions(result =>
{
if (result)
{
DTDSubscriptions.IsRestoreTransactionHistoryRequired((b) =>
{
if (b) DTDSubscriptions.History();
});
}
DTDSubscriptions.IsRestoring = false;
});
#endif
}
/// <summary>
/// Called when Unity IAP encounters an unrecoverable initialization error.
///
/// Note that this will not be called if Internet is unavailable; Unity IAP
/// will attempt initialization until it becomes available.
/// </summary>
public void OnInitializeFailed(InitializationFailureReason error)
{
Debug.Log($"IAP initialization error {error.ToString()}");
}
/// <summary>
/// Called when a purchase completes.
///
/// May be called at any time after OnInitialized().
/// </summary>
public PurchaseProcessingResult ProcessPurchase(PurchaseEventArgs e)
{
var product = e.purchasedProduct;
DTDSubscriptions.Payment(product);
return PurchaseProcessingResult.Complete;
}
/// <summary>
/// Called when a purchase fails.
/// </summary>
public void OnPurchaseFailed(Product i, PurchaseFailureReason p)
{
Debug.Log(p.ToString());
}
}
Onboarding (tutorial)
The event allows you to track tutorial completion and identify the stages where you lose new users.
We recommend tracking the starting point (value -1) before beginning the first tutorial stage, then passing the counting number of every completed stage after its completion (integers larger than 0), and at the end, marking the moment of the last tutorial stage completion (value -2).
If your app has an option of skipping the tutorial and the user has used it, then itโs necessary to send a refusal value (value 0) only.
DTDAnalytics.tutorial(step: 1)
The method takes on the step value with an integer type.
0
The user skipped the tutorial
-1
The value defines the beginning of the tutorial
1..int
Counting number of completed tutorial stage
-2
The value defines the completion of the tutorial
[DTDAnalytics tutorialStep:1];
The method takes on the step value with an integer type.
0
The user skipped the tutorial
-1
The value defines the beginning of the tutorial
1..int
Counting number of completed tutorial stage
-2
The value defines the completion of the tutorial
DTDAnalytics.tutorial(step = 1)
The method takes on the step value with an integer type.
0
The user skipped the tutorial
-1
The value defines the beginning of the tutorial
1..int
Counting number of completed tutorial stage
-2
The value defines the completion of the tutorial
DTDAnalytics.INSTANCE.tutorial(1);
The method takes on the step value with an integer type.
0
The user skipped the tutorial
-1
The value defines the beginning of the tutorial
1..int
Counting number of completed tutorial stage
-2
The value defines the completion of the tutorial
DTDAnalytics.Tutorial(1);
The method takes on the step value with an integer type.
0
The user skipped the tutorial
-1
The value defines the beginning of the tutorial
1..int
Counting number of completed tutorial stage
-2
The value defines the completion of the tutorial
DTDAnalytics.Tutorial(1);
The method takes on the step value with an int base type.
0
The user skipped the tutorial
-1