Record transaction events#

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.

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 the 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 under Administration in the Unity Cloud 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:

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.