Skip to main content

Track events

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

The Adtrace SDK provides an AdTraceEvent object that you use to structure and send event data. Create an event in the Adtrace panel, configure the AdTraceEvent instance, then call 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:

  1. Create an AdTraceEvent with your event token.
  2. Optionally add revenue, parameters, or a callback identifier.
  3. Call AdTrace.trackEvent(event) to send it (or use server-to-server events as an alternative).

Event object​

Configure what Adtrace sends by setting properties and parameters on an AdTraceEvent instance before you call AdTrace.trackEvent().

Create an AdTraceEvent instance​

Method signature​

public AdTraceEvent(String eventToken)
ParameterTypeDescription
eventTokenStringYour Adtrace event token from the Adtrace panel. Pass the event token, not the event name.

To send event information, create a new AdTraceEvent 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​

public void setRevenue(double revenue, String currency)
ParameterTypeDescription
revenuedoubleThe amount of revenue generated by the event.
currencyStringA 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 setting revenue and currency on your AdTraceEvent 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. This avoids tracking revenue that was not actually generated.

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

Example​

AdTraceEvent event = new AdTraceEvent("abc123");
event.setRevenue(52000, "IRR");
AdTrace.trackEvent(event);

Verify in LogCat​

Look for revenue and currency in the event request:

LogCat (example)
Path:      /event
ClientSdk: android2.6.0
Parameters:
  environment      sandbox
  event_count      3
  event_token      abc123
  revenue          2500.0
  currency         IRR

Deduplicate revenue events​

Method signature​

public void setOrderId(String orderId)
ParameterTypeDescription
orderIdStringA unique ID for this revenue transaction (for example a purchase order ID).

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 order ID with setOrderId so Adtrace can skip duplicates. The SDK remembers the last 10 order IDs and skips revenue events that reuse one of them. This is especially useful for in-app purchases.

Example​

AdTraceEvent event = new AdTraceEvent("abc123");
event.setRevenue(52000, "IRR");
event.setOrderId("{OrderId}");
AdTrace.trackEvent(event);

Example: purchase with order ID​

public void onTrackPurchaseEventClick(View v) {
    AdTraceEvent event = new AdTraceEvent("abc123");
    event.setRevenue(52000, "IRR");
    event.setOrderId("5e85484b-1ebc-4141-aab7-25b869e54c49");
    AdTrace.trackEvent(event);
}

Verify in LogCat​

Look for order_id in the event request:

LogCat (example)
Path:      /event
ClientSdk: android2.6.0
Parameters:
  environment      sandbox
  event_count      3
  event_token      abc123
  order_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 typeMethodSent toAppears in panel?
Callback parametersaddCallbackParameterYour registered callback URLNo (raw callback data only)
Event parametersaddEventParameterAdtrace servers with the eventNo (raw data only)
Partner parametersaddPartnerParameterEnabled network partnersNo by default

Guidance:

  • Use callback parameters for values you collect for your own internal systems (for example BI callbacks).
  • Use event parameters for values you want 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 parameters​

Method signature​

public void addEventParameter(String key, String value)
ParameterTypeDescription
keyStringThe parameter name.
valueStringThe parameter value.

When you want to send any value with an event, add event parameters by calling addEventParameter on your AdTraceEvent 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 parameters. Use setRevenue instead.

Example​

AdTraceEvent event = new AdTraceEvent("abc123");
event.addEventParameter("key", "value");
event.addEventParameter("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​

public void addCallbackParameter(String key, String value)
ParameterTypeDescription
keyStringThe callback parameter name.
valueStringThe callback parameter value. You can also use placeholders such as {gps_adid}.

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 on your AdTraceEvent instance before AdTrace.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​

AdTraceEvent 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 {gps_adid}). In the callback request, Adtrace replaces the placeholder with the matching device value.

Verify in LogCat​

Look for callback_params in the event request:

LogCat (example)
Path:      /event
ClientSdk: android2.6.0
Parameters:
  callback_params  {"key":"value","foo":"bar"}
  environment      sandbox
  event_count      1
  event_token      g3mfiw

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​

public void addPartnerParameter(String key, String value)
ParameterTypeDescription
keyStringThe partner parameter name.
valueStringThe partner parameter value.

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

Example​

AdTraceEvent 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.

public void onTrackUniqueEventClick(View v) {
    AdTraceEvent event = new AdTraceEvent("g3mfiw");
    event.addPartnerParameter("product_id", "29");
    event.addPartnerParameter("user_id", "835");
    AdTrace.trackEvent(event);
}

Verify in LogCat​

Look for partner_params in the event request:

LogCat (example)
Path:      /event
ClientSdk: android2.6.0
Parameters:
  partner_params  {"product_id":"29","user_id":"835"}
  environment      sandbox
  event_count      1
  event_token      g3mfiw

Add a callback identifier​

Method signature​

public void setCallbackId(String callbackId)
ParameterTypeDescription
callbackIdStringA custom string ID for this event instance.

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

Call setCallbackId on your AdTraceEvent instance before AdTrace.trackEvent().

Example​

AdTraceEvent event = new AdTraceEvent("abc123");
event.setCallbackId("Your-Custom-Id");
AdTrace.trackEvent(event);

Example: button tap with callback ID​

public void onTrackUniqueEventClick(View v) {
    AdTraceEvent event = new AdTraceEvent("g3mfiw");
    event.setCallbackId("f2e728d8-271b-49ab-80ea-27830a215147");
    AdTrace.trackEvent(event);
}

Verify in LogCat​

Look for callback_id in the event request:

LogCat (example)
Path:      /event
ClientSdk: android2.6.0
Parameters:
  environment      sandbox
  event_count      3
  event_token      g3mfiw
  callback_id      f2e728d8-271b-49ab-80ea-27830a215147

Send an event​

After you configure your AdTraceEvent instance, call AdTrace.trackEvent() whenever the action occurs in your app. For server-side delivery, see Server-to-server events.

Method signature​

public static void trackEvent(AdTraceEvent event)
ParameterTypeDescription
eventAdTraceEventThe configured event instance to send.

Call AdTrace.trackEvent() with your AdTraceEvent instance whenever the action occurs in your app.

Example​

AdTraceEvent 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.

public void onTrackSimpleEventClick(View v) {
    AdTraceEvent event = new AdTraceEvent("abc123");
    AdTrace.trackEvent(event);
}

Verify in LogCat​

Set log level to VERBOSE or DEBUG, filter LogCat with the AdTrace tag, then send the event. A successful /event request includes your token and environment:

LogCat (example)
Path:      /event
ClientSdk: android2.6.0
Parameters:
  android_uuid     781f17d5-5048-4fae-a4e5-77b58bab62b9
  api_level        34
  app_token        2fm9gkqubvpc
  app_version      1.0
  connectivity_type 1
  country          US
  created_at       2024-01-25T14:13:16.151Z+0100
  device_manufacturer Google
  device_name      sdk_gphone64_arm64
  device_type      phone
  environment      sandbox
  event_count      3
  event_token      abc123
  gps_adid         5962dfc1-3a53-4692-850b-22c4bf4311a5
  language         en
  os_name          android
  os_version       14
  package_name     com.example.app
  session_count    2
  tracking_enabled 1

Key fields: event_token, event_count, environment

Verify your events​

Before sending events in production:

  1. Ensure install was successfully tracked on the test device.
  2. Set log level to VERBOSE or DEBUG and confirm /event requests in LogCat.
  3. Check the Testing Console in the panel (Settings → Testing Console).

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