Tracking Conversions

Conversion tracking lets you record goal completions for visitors bucketed into experiences. The SDK evaluates the goal's configured triggering rules and sends conversion (and optionally transaction) events to the Convert tracking API.

Basic Conversion Tracking

Track a goal conversion by passing its unique key:

userContext.trackConversion('goal-key');

$context->trackConversion('goal-key');

Conversion Attributes

You can pass additional attributes to control rule matching, attach revenue data, and configure tracking behavior:

userContext.trackConversion('goal-key', {
  ruleData: {
    action: 'buy'
  },
  conversionData: [
    { key: 'amount', value: 10.3 },
    { key: 'productsCount', value: 2 },
    { key: 'transactionId', value: 'transaction-unique-id' }
  ],
  conversionSetting: {
    forceMultipleTransactions: false
  }
});

use ConvertSdk\DTO\ConversionAttributes;
use ConvertSdk\DTO\GoalData;
use ConvertSdk\Enums\GoalDataKey;

$context->trackConversion('goal-key', new ConversionAttributes(
    ruleData: [
        'action' => 'buy',
    ],
    conversionData: [
        new GoalData(GoalDataKey::Amount, 10.3),
        new GoalData(GoalDataKey::ProductsCount, 2),
        new GoalData(GoalDataKey::TransactionId, 'transaction-unique-id'),
    ],
    conversionSetting: [
        'forceMultipleTransactions' => false,
    ],
));

Attributes Reference

Property	Type	Description
`ruleData`	object / array	Key-value pairs used for goal rule matching. The conversion only fires if the rules match.
`conversionData`	array	Transaction data entries (see below). When present, the SDK sends both a conversion event and a transaction event.
`conversionSetting`	object / array	Tracking behavior overrides. Supports `forceMultipleTransactions` (boolean).

conversionData Keys

Key	Type	Description
`amount`	number	Order value
`productsCount`	number	Order quantity
`transactionId`	string or number	Unique transaction identifier

The PHP SDK also supports customDimension1 through customDimension5 for additional custom data.

Revenue Tracking

To report revenue, include conversionData with your conversion. At minimum, pass amount and transactionId:

userContext.trackConversion('purchase-completed', {
  conversionData: [
    { key: 'amount', value: 99.99 },
    { key: 'productsCount', value: 3 },
    { key: 'transactionId', value: 'txn-abc-123' }
  ]
});

use ConvertSdk\DTO\ConversionAttributes;
use ConvertSdk\DTO\GoalData;
use ConvertSdk\Enums\GoalDataKey;

$context->trackConversion('purchase-completed', new ConversionAttributes(
    conversionData: [
        new GoalData(GoalDataKey::Amount, 99.99),
        new GoalData(GoalDataKey::ProductsCount, 3),
        new GoalData(GoalDataKey::TransactionId, 'txn-abc-123'),
    ],
));

When conversionData is present, the SDK sends two events: a conversion event and a transaction event containing the goal data.

Force Multiple Transactions

By default, each goal fires once per visitor per experience. Subsequent calls to trackConversion for the same visitor and goal are silently ignored (deduplication).

For recurring transactions such as subscription renewals, override deduplication by setting forceMultipleTransactions to true:

userContext.trackConversion('subscription-renewal', {
  conversionData: [
    { key: 'amount', value: 29.99 },
    { key: 'transactionId', value: 'renewal-456' }
  ],
  conversionSetting: {
    forceMultipleTransactions: true
  }
});

use ConvertSdk\DTO\ConversionAttributes;
use ConvertSdk\DTO\GoalData;
use ConvertSdk\Enums\GoalDataKey;
use ConvertSdk\Enums\ConversionSettingKey;

$context->trackConversion('subscription-renewal', new ConversionAttributes(
    conversionData: [
        new GoalData(GoalDataKey::Amount, 29.99),
        new GoalData(GoalDataKey::TransactionId, 'renewal-456'),
    ],
    conversionSetting: [
        ConversionSettingKey::ForceMultipleTransactions->value => true,
    ],
));

Behavior Summary

Scenario	Conversion Event	Transaction Event
First trigger, no goal data	Sent	Not sent
First trigger, with goal data	Sent	Sent
Repeat trigger, no force	Not sent	Not sent
Repeat trigger, force=true, no goal data	Not sent	Not sent
Repeat trigger, force=true, with goal data	Not sent	Sent

Note: When forceMultipleTransactions is enabled on a repeat trigger, only the transaction event is sent (revenue is accumulated). The conversion event itself is still deduplicated -- it only fires once per visitor per experience.