Record transaction events

Track in-app purchases and failed transactions to measure revenue and monitor transaction health.

Read time 3 minutes

Last updated 2 months ago

Use the

transaction

event to track successful in-app purchases via the revenue KPIs in the dashboard. This event contains arrays and some special

Product

objects to capture multiple items and currencies spent or bought in a single transaction. You might be developing an RPG where the player can buy and receive heroes, gear and resources from multiple points such as the shop, popup offers, and a daily reward system. The

transaction

event has parameters to help register most of the information about your transactions. Unsuccessful transactions are tracked under a dedicated

transactionFailed

event, containing details regarding the purchase transaction and the reason for its failure. This doesn't contribute to the revenue metrics in the dashboards. You can send the

transaction

and

transactionFailed

events manually via the SDK or REST API. If you're using Unity IAP version 4.2 or higher, it automatically sends these events for you.

Warning

Sending transactions manually to Analytics while also using the IAP plug-in counts them twice and reports inflated revenue.

Important

Transaction events received from Apple and Google sandbox purchases can be reviewed in the Analytics > SQL Data Explorer tool, but they don't contribute towards dashboard Revenue reports.

Send events manually

The Analytics SDK provides the

TransactionEvent

and

TransactionFailedEvent

classes to help you record these events successfully. If you are using the REST API, you can refer to their schemas in the Event Manager.

Record automatically using the IAP plug-in

Transactions made by Unity IAP are automatically forwarded to Analytics using the same

transaction

event schema as when you send the events manually. The transaction event contributes to the revenue KPIs available in Analytics. Unsuccessful transactions are also automatically tracked by the IAP plug-in using the

transactionFailed

event. If you are using Unity IAP, you don't need to record transactions manually.

Report successful purchases

In the following example, the

transaction

event records the player spending $4.99 of real US dollars to purchase a treasure chest which contains virtual currency and multiple items. Use the following code to create the

transaction

event:


public void SendTransaction(){	TransactionEvent transaction = new TransactionEvent	{		TransactionId = "100000576198248",		TransactionName = "IAP - A Large Treasure Chest",		TransactionType = TransactionType.PURCHASE,		TransactionServer = TransactionServer.APPLE,		TransactionReceipt = "ewok9Ja81............991KS=="	};	transaction.ReceivedItems.Add(new TransactionItem {		ItemName = "Golden Battle Axe", ItemType = "Weapon", ItemAmount = 1	});	transaction.ReceivedItems.Add(new TransactionItem {		ItemName = "Flaming Sword", ItemType = "Weapon", ItemAmount = 1	});	transaction.ReceivedItems.Add(new TransactionItem {		ItemName = "Jewel Encrusted Shield", ItemType = "Armour", ItemAmount = 1	});	transaction.ReceivedVirtualCurrencies.Add(new TransactionVirtualCurrency	{		VirtualCurrencyName = "Gold",		VirtualCurrencyType = VirtualCurrencyType.PREMIUM,		VirtualCurrencyAmount = 100	});	transaction.SpentRealCurrency = new TransactionRealCurrency	{		RealCurrencyType = "USD",		RealCurrencyAmount = AnalyticsService.Instance.ConvertCurrencyToMinorUnits("USD", 4.99)	};	AnalyticsService.Instance.RecordEvent(transaction);}

Report failed purchases

The

transactionFailed

event captures unsuccessful in-app purchases. Purchases can fail for a number of reasons, including network failure, payment failure, or device settings. In the following example the

transactionFailed

event records the player's attempt to spend $4.99 of real US dollars to purchase a treasure chest that contains virtual currency and multiple items, where the user cancels the purchase. Use the following code to create the

transactionFailed

event:


public void SendTransactionFailed(){	TransactionFailedEvent transactionFailed = new TransactionFailedEvent	{		FailureReason = "cancelled",		TransactionId = "100000576198248",		TransactionName = "IAP - A Large Treasure Chest",		TransactionType = TransactionType.PURCHASE,		TransactionServer = TransactionServer.APPLE	};	transactionFailed.ReceivedItems.Add(new TransactionItem {		ItemName = "Golden Battle Axe", ItemType = "Weapon", ItemAmount = 1	});	transactionFailed.ReceivedItems.Add(new TransactionItem {		ItemName = "Flaming Sword", ItemType = "Weapon", ItemAmount = 1	});	transactionFailed.ReceivedItems.Add(new TransactionItem {		ItemName = "Jewel Encrusted Shield", ItemType = "Armour", ItemAmount = 1	});	transactionFailed.ReceivedVirtualCurrencies.Add(new TransactionVirtualCurrency	{		VirtualCurrencyName = "Gold",		VirtualCurrencyType = VirtualCurrencyType.PREMIUM,		VirtualCurrencyAmount = 100	});	transactionFailed.SpentRealCurrency = new TransactionRealCurrency	{		RealCurrencyType = "USD",		RealCurrencyAmount = AnalyticsService.Instance.ConvertCurrencyToMinorUnits("USD", 4.99)	};	AnalyticsService.Instance.RecordEvent(transactionFailed);}

Validate transactions

Transaction validation checks to see if a transaction is a legitimate purchase. The platform can undertake transaction receipt validation with iOS and Android stores in order to ensure that any revenue displayed in your dashboards is genuine revenue and not the result of a hacked or jailbroken game. To use transaction validation you'll need to:

Provide the validation key for the relevant store so the Analytics platform can validate the receipt against the store. You can do this in the Administration menu in the Unity Dashboard.
Include the receipt validation parameters in the
```
transaction
```
event, to inform the platform that the transaction should be validated (this will vary depending on the store).

The transaction event contains a

revenueValidated

parameter, used by IAP receipt validation services, which is populated automatically if you're using revenue validation. The available values are:

Value	Result
0	This transaction has not used the revenue validation service and is included in your revenue charts.
1	This transaction has passed verification and is included in your revenue charts.
2	This transaction has failed verification and is NOT included in your revenue charts.
3	This transaction could not be verified due to an error and is NOT included in your revenue charts.

Apple Store

Analytics automatically attempts receipt validation on iOS transactions. Add the following to iOS transactions to validate the receipt:


	TransactionEvent transaction = new TransactionEvent	{		TransactionServer = TransactionServer.APPLE,		TransactionId = "100000576198248",		TransactionReceipt = "ewok9Ja81............991KS=="	};

The

transactionReceipt

is the base-64 encoded receipt data returned from Apple. Refer to the Apple developer website for details on Apple Receipt Validation.

Google Play

You must provide the Google public key. To update the Google key go to Project Settings > In-app purchase (IAP) settings and populate the Google License Key. Add the following to the transaction event to Android transactions to validate the receipt:


	TransactionEvent transaction = new TransactionEvent	{		TransactionServer = TransactionServer.GOOGLE,		TransactionReceipt = "{	\"orderId\":\"GPA.1234-5678-9012-34567\",	\"packageName\":\"com.example.app\",	\"productId\":\"exampleSku\",	\"purchaseTime\":1345678900000,	\"purchaseState\":0,	\"developerPayload\":\"bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ\",	\"purchaseToken\":\"opaque-token-up-to-1000-characters\"}",		TransactionReceiptSignature = "rNvoHwiBdLSW+........VncbYVJ61fmfsQ=="	}

Important

Since the transaction receipt and a private key generates the

transactionReceiptSignature

, in order to validate the receipt it must be the exact string provided by Google and passed as a string, not a nested JSON object.

Documentation

Development

User Acquisition

Monetization

Industry