Track events

Use the methods in this guide to send event information from your app to Adtrace.

The Adtrace SDK provides an ADTEvent object that you use to structure and send event data. Create an event in the Adtrace panel, configure the ADTEvent instance, then call [Adtrace trackEvent:] / Adtrace.trackEvent(...).

Important

Before you send events, ensure the install was successfully tracked for the app on the device. If no install is recorded, Adtrace may still receive and store your events, but they will not appear in panel statistics.

Typical flow:

Create an ADTEvent with your event token.
Optionally add revenue, parameters, or a callback identifier.
Call trackEvent to send it.

Event object

Configure what Adtrace sends by setting properties and parameters on an ADTEvent instance before you call trackEvent.

Create an ADTEvent instance

Method signature

+ (nullable ADTEvent *)eventWithEventToken:(nonnull NSString *)eventToken;

Parameter	Type	Description
`eventToken`	`NSString`	Your Adtrace event token from the Adtrace panel. Pass the event token, not the event name.

To send event information, create a new ADTEvent instance and pass your event token. This object holds the data the SDK sends when the event occurs in your app.

tip

Unique events are configured in the panel when you create the event (Settings → Event). Unique events are stored only the first time on a device; non-unique events are stored on every trigger. No extra SDK flag is required.
There is no limit on how many event instances you can send per user or over time (for non-unique events).
The SDK queues events on the device and keeps retrying until Adtrace servers accept them successfully.

Replace abc123 in the examples below with your event token from the Adtrace panel.

Record event revenue

Method signature

- (void)setRevenue:(double)amount currency:(nonnull NSString *)currency;

Parameter	Type	Description
`amount`	`double`	The amount of revenue generated by the event.
`currency`	`NSString`	A currency label for this revenue (for example `IRR`, `EUR`, or `USD`). Adtrace does not convert between currencies. Prefer sending all revenue in a single currency.

You can record revenue associated with an event by calling setRevenue:currency: on your ADTEvent instance. Use this for revenue-generating actions such as ads or in-app purchases.

Revenue can be combined with callback parameters.

Important

For in-app purchases, call trackEvent only after the purchase is finished and the item has been purchased (for example after finishTransaction when the state is SKPaymentTransactionStatePurchased). This avoids tracking revenue that was not actually generated.

Do not send revenue through event value parameters. Always use setRevenue.

Example

Objective-C
Swift
Javascript

ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];
[event setRevenue:52000.0 currency:@"IRR"];
[Adtrace trackEvent:event];

let event = ADTEvent(eventToken: "abc123")
event?.setRevenue(52000.0, currency: "IRR")
Adtrace.trackEvent(event)

let event = new AdtraceEvent('abc123');
event.setRevenue(52000.0, 'IRR');
Adtrace.trackEvent(event);

Verify in Xcode console

Set log level to ADTLogLevelVerbose or ADTLogLevelDebug, then look for revenue and currency in the /event request:

Xcode console (example)
Path:      /event
Parameters:
  event_token      abc123
  revenue          52000.0
  currency         IRR

Deduplicate revenue events

Method signature

- (void)setTransactionId:(nonnull NSString *)transactionId;

Parameter	Type	Description
`transactionId`	`NSString`	A unique ID for this revenue transaction (for example a StoreKit transaction identifier).

Revenue events are often compared to real purchase data. Duplicate revenue is common when a user taps purchase more than once (for example because of a slow network).

Pass an optional transaction ID with setTransactionId: so Adtrace can skip duplicates. The SDK remembers the last 10 transaction IDs and skips revenue events that reuse one of them. This is especially useful for in-app purchases.

Example

Objective-C
Swift
Javascript

ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];
[event setRevenue:52000.0 currency:@"IRR"];
[event setTransactionId:@"{TransactionId}"];
[Adtrace trackEvent:event];

let event = ADTEvent(eventToken: "abc123")
event?.setRevenue(52000.0, currency: "IRR")
event?.setTransactionId("{TransactionId}")
Adtrace.trackEvent(event)

let event = new AdtraceEvent('abc123');
event.setRevenue(52000.0, 'IRR');
event.setTransactionId('{TransactionId}');
Adtrace.trackEvent(event);

Example: in-app purchase with transaction ID

Objective-C
Swift

- (void)paymentQueue:(SKPaymentQueue *)queue updatedTransactions:(NSArray *)transactions {
    for (SKPaymentTransaction *transaction in transactions) {
        if (transaction.transactionState == SKPaymentTransactionStatePurchased) {
            [[SKPaymentQueue defaultQueue] finishTransaction:transaction];

            ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];
            [event setRevenue:52000.0 currency:@"IRR"];
            [event setTransactionId:transaction.transactionIdentifier];
            [Adtrace trackEvent:event];
        }
    }
}

func paymentQueue(_ queue: SKPaymentQueue, updatedTransactions transactions: [SKPaymentTransaction]) {
    for transaction in transactions where transaction.transactionState == .purchased {
        SKPaymentQueue.default().finishTransaction(transaction)

        let event = ADTEvent(eventToken: "abc123")
        event?.setRevenue(52000.0, currency: "IRR")
        event?.setTransactionId(transaction.transactionIdentifier)
        Adtrace.trackEvent(event)
    }
}

Verify in Xcode console

Look for transaction_id or order_id in the event request (field name may vary by SDK version):

Xcode console (example)
Path:      /event
Parameters:
  event_token      abc123
  transaction_id   5e85484b-1ebc-4141-aab7-25b869e54c49

Custom parameters overview

In addition to the data the Adtrace SDK collects by default, you can attach custom key-value data to events.

Parameter type	Method	Sent to	Appears in panel?
Callback parameters	`addCallbackParameter:value:`	Your registered callback URL	No (raw callback data only)
Event value parameters	`addEventValueParameter:value:`	Adtrace servers with the event	No (raw data only)
Partner parameters	`addPartnerParameter:value:`	Enabled network partners	No by default

Guidance:

Use callback parameters for values you collect for your own internal systems (for example BI callbacks).
Use event value parameters for values activated in the panel or attached to the event payload.
Use partner parameters for extra data sent to network partners you have configured.
If a value (for example a product ID) is needed in more than one place, you can use multiple parameter types.

Add event value parameters

Method signature

- (void)addEventValueParameter:(nonnull NSString *)key value:(nonnull NSString *)value;

Parameter	Type	Description
`key`	`NSString`	The parameter name.
`value`	`NSString`	The parameter value.

When you want to send any value with an event, add event value parameters by calling addEventValueParameter:value: on your ADTEvent instance. Call it once per pair. You can add multiple parameters.

If you defined keys for this event in the panel (Settings → Event → Add key), the key strings in code must match the panel exactly, including upper and lower case.

Important

Do not send revenue in event value parameters. Use setRevenue instead.

Example

Objective-C
Swift
Javascript

ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];
[event addEventValueParameter:@"key" value:@"value"];
[event addEventValueParameter:@"foo" value:@"bar"];
[Adtrace trackEvent:event];

let event = ADTEvent(eventToken: "abc123")
event?.addEventValueParameter("key", value: "value")
event?.addEventValueParameter("foo", value: "bar")
Adtrace.trackEvent(event)

let event = new AdtraceEvent('abc123');
event.addEventValueParameter('key', 'value');
event.addEventValueParameter('foo', 'bar');
Adtrace.trackEvent(event);

Add callback parameters

Session-level callback parameters apply to every session and event. See Set session callback parameters to add, remove, or reset them on Adtrace.

Method signature

- (void)addCallbackParameter:(nonnull NSString *)key value:(nonnull NSString *)value;

Parameter	Type	Description
`key`	`NSString`	The callback parameter name.
`value`	`NSString`	The callback parameter value. You can also use placeholders such as `{idfa}`.

If you register a callback URL for an event in the Adtrace panel, Adtrace sends a GET request to that URL when the event is tracked.

Use callback parameters to append custom key-value data to that URL. Call addCallbackParameter:value: on your ADTEvent instance before trackEvent.

tip

Adtrace does not store your custom callback parameters. They are only appended to your callback URL. If the event has no callback URL registered, these parameters are not read.

Example

Objective-C
Swift
Javascript

ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];
[event addCallbackParameter:@"key" value:@"value"];
[event addCallbackParameter:@"foo" value:@"bar"];
[Adtrace trackEvent:event];

let event = ADTEvent(eventToken: "abc123")
event?.addCallbackParameter("key", value: "value")
event?.addCallbackParameter("foo", value: "bar")
Adtrace.trackEvent(event)

let event = new AdtraceEvent('abc123');
event.addCallbackParameter('key', 'value');
event.addCallbackParameter('foo', 'bar');
Adtrace.trackEvent(event);

If you registered http://www.example.com/callback, the request looks like:

http://www.example.com/callback?key=value&foo=bar

You can use placeholders in parameter values (for example {idfa}). In the callback request, Adtrace replaces the placeholder with the matching device value.

Verify in Xcode console

Look for callback_params in the event request:

Xcode console (example)
Path:      /event
Parameters:
  callback_params  {"key":"value","foo":"bar"}
  event_token      abc123

Add partner parameters

Send extra information to your network partners by adding partner parameters to an event.

Adtrace forwards partner parameters to external partners you have set up in the panel. This data is useful for granular analysis and retargeting. Parameters are forwarded once you configure and enable them for a partner.

note

Partner parameters do not appear in raw data by default. You can add the {partner_parameters} placeholder to receive them as a single string in callbacks.

Method signature

- (void)addPartnerParameter:(nonnull NSString *)key value:(nonnull NSString *)value;

Parameter	Type	Description
`key`	`NSString`	The partner parameter name.
`value`	`NSString`	The partner parameter value.

Add partner parameters by calling addPartnerParameter:value: with string key-value pairs. Call the method multiple times to add multiple parameters.

Example

Objective-C
Swift
Javascript

ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];
[event addPartnerParameter:@"key" value:@"value"];
[event addPartnerParameter:@"foo" value:@"bar"];
[Adtrace trackEvent:event];

let event = ADTEvent(eventToken: "abc123")
event?.addPartnerParameter("key", value: "value")
event?.addPartnerParameter("foo", value: "bar")
Adtrace.trackEvent(event)

let event = new AdtraceEvent('abc123');
event.addPartnerParameter('key', 'value');
event.addPartnerParameter('foo', 'bar');
Adtrace.trackEvent(event);

Example: button tap with partner parameters

This example records an event with token g3mfiw when a user taps a button. It adds product_id and user_id as partner parameters.

Objective-C
Swift
Javascript

- (IBAction)onTrackUniqueEventTap:(id)sender {
    ADTEvent *event = [ADTEvent eventWithEventToken:@"g3mfiw"];
    [event addPartnerParameter:@"product_id" value:@"29"];
    [event addPartnerParameter:@"user_id" value:@"835"];
    [Adtrace trackEvent:event];
}

@IBAction func onTrackUniqueEventTap(_ sender: Any) {
    let event = ADTEvent(eventToken: "g3mfiw")
    event?.addPartnerParameter("product_id", value: "29")
    event?.addPartnerParameter("user_id", value: "835")
    Adtrace.trackEvent(event)
}

function onTrackUniqueEventTap() {
    let event = new AdtraceEvent('g3mfiw');
    event.addPartnerParameter('product_id', '29');
    event.addPartnerParameter('user_id', '835');
    Adtrace.trackEvent(event);
}

Verify in Xcode console

Look for partner_params in the event request:

Xcode console (example)
Path:      /event
Parameters:
  partner_params  {"product_id":"29","user_id":"835"}
  event_token     g3mfiw

Add a callback identifier

Method signature

- (void)setCallbackId:(nonnull NSString *)callbackId;

Parameter	Type	Description
`callbackId`	`NSString`	A custom string ID for this event instance.

You can add a custom string identifier to each event you track. Adtrace reports this identifier in event success and failure callbacks so you can tell which events were successfully tracked.

Call setCallbackId: on your ADTEvent instance before trackEvent.

Example

Objective-C
Swift
Javascript

ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];
[event setCallbackId:@"Your-Custom-Id"];
[Adtrace trackEvent:event];

let event = ADTEvent(eventToken: "abc123")
event?.setCallbackId("Your-Custom-Id")
Adtrace.trackEvent(event)

let event = new AdtraceEvent('abc123');
event.setCallbackId('Your-Custom-Id');
Adtrace.trackEvent(event);

Example: button tap with callback ID

Objective-C
Swift
Javascript

- (IBAction)onTrackUniqueEventTap:(id)sender {
    ADTEvent *event = [ADTEvent eventWithEventToken:@"g3mfiw"];
    [event setCallbackId:@"f2e728d8-271b-49ab-80ea-27830a215147"];
    [Adtrace trackEvent:event];
}

@IBAction func onTrackUniqueEventTap(_ sender: Any) {
    let event = ADTEvent(eventToken: "g3mfiw")
    event?.setCallbackId("f2e728d8-271b-49ab-80ea-27830a215147")
    Adtrace.trackEvent(event)
}

function onTrackUniqueEventTap() {
    let event = new AdtraceEvent('g3mfiw');
    event.setCallbackId('f2e728d8-271b-49ab-80ea-27830a215147');
    Adtrace.trackEvent(event);
}

Verify in Xcode console

Look for callback_id in the event request:

Xcode console (example)
Path:      /event
Parameters:
  event_token      g3mfiw
  callback_id      f2e728d8-271b-49ab-80ea-27830a215147

Send an event

After you configure your ADTEvent instance, call trackEvent whenever the action occurs in your app.

Method signature

+ (void)trackEvent:(nullable ADTEvent *)event;

Parameter	Type	Description
`event`	`ADTEvent`	The configured event instance to send.

Example

Objective-C
Swift
Javascript

ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];
[Adtrace trackEvent:event];

let event = ADTEvent(eventToken: "abc123")
Adtrace.trackEvent(event)

let event = new AdtraceEvent('abc123');
Adtrace.trackEvent(event);

Example: track a button tap

This example records an event with token abc123 whenever a user taps a button.

Objective-C
Swift
Javascript

- (IBAction)onTrackSimpleEventTap:(id)sender {
    ADTEvent *event = [ADTEvent eventWithEventToken:@"abc123"];
    [Adtrace trackEvent:event];
}

@IBAction func onTrackSimpleEventTap(_ sender: Any) {
    let event = ADTEvent(eventToken: "abc123")
    Adtrace.trackEvent(event)
}

function onTrackSimpleEventTap() {
    let event = new AdtraceEvent('abc123');
    Adtrace.trackEvent(event);
}

Verify in Xcode console

Set log level to ADTLogLevelVerbose or ADTLogLevelDebug, then send the event. A successful /event request includes your token and environment:

Xcode console (example)
Path:      /event
Parameters:
  app_token        {YourAppToken}
  environment      sandbox
  event_count      3
  event_token      abc123
  os_name          ios

Key fields: event_token, event_count, environment

Verify your events

Before sending events in production:

Ensure install was successfully tracked on the test device.
Set log level to ADTLogLevelVerbose or ADTLogLevelDebug and confirm /event requests in the Xcode console.
Check the Testing Console in the panel (Settings → Testing Console).

To run code when an event succeeds or fails, see Send callback information.

Event object​

Create an ADTEvent instance​

Method signature​

Record event revenue​

Method signature​

Example​

Verify in Xcode console​

Deduplicate revenue events​

Method signature​

Example​

Example: in-app purchase with transaction ID​

Verify in Xcode console​

Custom parameters overview​

Add event value parameters​

Method signature​

Example​

Add callback parameters​

Method signature​

Example​

Verify in Xcode console​

Add partner parameters​

Method signature​

Example​

Example: button tap with partner parameters​

Verify in Xcode console​

Add a callback identifier​

Method signature​

Example​

Example: button tap with callback ID​

Verify in Xcode console​

Send an event​

Method signature​

Example​

Example: track a button tap​

Verify in Xcode console​

Verify your events​

Related​

Event object

Create an ADTEvent instance

Method signature

Record event revenue

Method signature

Example

Verify in Xcode console

Deduplicate revenue events

Method signature

Example

Example: in-app purchase with transaction ID

Verify in Xcode console

Custom parameters overview

Add event value parameters

Method signature

Example

Add callback parameters

Method signature

Example

Verify in Xcode console

Add partner parameters

Method signature

Example

Example: button tap with partner parameters

Verify in Xcode console

Add a callback identifier

Method signature

Example

Example: button tap with callback ID

Verify in Xcode console

Send an event

Method signature

Example

Example: track a button tap

Verify in Xcode console

Verify your events

Related