GuidesAPI Reference
Submit Documentation FeedbackJoin Developer CommunityLog In

Tag events

Use cases

Event tags are contextual metadata about conversion events. You can use event tags to:

  • Enrich your exported Optimizely experiment data, for example so that you can reconcile Optimizely data with data from other company systems. For example, for a product purchase event, you may want to attach additional metadata tags such as a product SKU, product category, order ID, and purchase amount.
  • Track numeric metrics on the Results page (for more information, see Reserved tag keys.

Event tags do not affect audiences, and with the exception of reserved tags, don't affect the Results page. They do not need to be registered in the Optimizely app.

Implement tags

You can include event tags as an optional key-value argument when you call the Track method. Event tags are distinct from user attributes, which should be reserved for user-level targeting and segmentation. Event tags can be strings, integers, floating-point numbers, or Boolean values.

See the following example:

String eventKey = "my_conversion";
String userId = "user123";

Map<String, String> attributes = new HashMap<String, String>();
attributes.put("DEVICE", "iPhone");
attributes.put("AD_SOURCE", "my_campaign");

Map<String, Object> eventTags = new HashMap<String, Object>();
eventTags.put("purchasePrice", 64.32f);
eventTags.put("category", "shoes");

// Reserved "revenue" tag
eventTags.put("revenue", 6432);

// Reserved "value" tag
eventTags.put("value", 4);

Optimizely optimizelyClient = optimizelyManager.getOptimizely();

// Track event with user attributes and event tags
optimizelyClient.track(eventKey, userId, attributes, eventTags);
using OptimizelySDK.Entity;

var eventKey = "my_conversion";
var userId = "user123";

UserAttributes attributes = new UserAttributes
{
    { "DEVICE", "iPhone" },
    { "AD_SOURCE", "my_campaign" }
};

EventTags tags = new EventTags
{
    { "purchasePrice", 64.32 },
    { "category", "shoes" },
    { "revenue", 6432 },  // Reserved "revenue" tag
    { "value", 4 }  // Reserved "value" tag
};

// Track event with user attributes and event tags
OptimizelyClient.Track(eventKey, userId, attributes, tags);
String eventKey = "my_conversion";
String userId = "user123";

Map<String, String> attributes = new HashMap<String, String>();
attributes.put("DEVICE", "iPhone");
attributes.put("AD_SOURCE", "my_campaign");

Map<String, Object> eventTags = new HashMap<String, Object>();
eventTags.put("purchasePrice", 64.32f);
eventTags.put("category", "shoes");

// Reserved "revenue" tag
eventTags.put("revenue", 6432);

// Reserved "value" tag
eventTags.put("value", 4);

// Track event with user attributes and event tags
optimizelyClient.track(eventKey, userId, attributes, eventTags);
const eventKey = 'my_conversion';
const userId = 'user123';

const attributes = {
  DEVICE: 'iPhone',
  AD_SOURCE: 'my_campaign',
};

const eventTags = {
  category: 'shoes',
  purchasePrice: 64.32,
  revenue: 6432, // reserved "revenue" tag
  value: 4, // reserved "value" tag
};

// Track event with user attributes and event tags
optimizelyClient.track(eventKey, userId, attributes, eventTags);
NSDictionary *attributes = @{@"device" : @"iPhone", @"ad_source" : @"my_campaign"};

NSDictionary *eventTags = @{
  @"purchasePrice" : @64.32,
  @"category" : @"shoes",
  @"revenue": @6432  // reserved "revenue" tag
};

// Track event with user attributes and event tags
[optimizely track:@"my_conversion"
           userId:@"user123"
       attributes:attributes
       eventTags:eventTags];
$eventKey = 'my_conversion';
$userId = 'user123';

$attributes = [
    'device' => 'iphone',
    'ad_source' => 'my_campaign'
];

$eventTags = [
    'category' => 'shoes',
    'purchasePrice' => 64.32,
    'revenue' => 6432, // reserved "revenue" tag
    'value' => 4 // reserved "value" tag
];

// Track event with user attributes and event tags
$optimizelyClient->track($eventKey, $userId, $attributes, $eventTags);

// Track event with event tags and without user attributes
$optimizelyClient->track($eventKey, $userId, null, $eventTags);
event_key = 'my_conversion'
user_id = 'user123'

attributes = {
  'device': 'iPhone',
  'adSource': 'my_campaign'
}

event_tags = {
  'category': 'shoes',
  'purchasePrice': 64.32,
  'revenue': 6432,  # reserved "revenue" tag
  'value': 4 # reserved "value" tag
}

# Track event with user attributes and event tags
optimizely_client.track(event_key, user_id, attributes, event_tags)

# Track event with event tags and without user attributes
optimizely_client.track(event_key, user_id, event_tags=event_tags)
event_key = 'my_conversion'
user_id = 'user123'

attributes = {
  'device' => 'iPhone',
  'adSource' => 'my_campaign'
}

event_tags = {
  'category' => 'shoes',
  'purchasePrice' => 64.32,
  'revenue' => 6432,  # reserved "revenue" tag
  'value' => 4 # reserved "value" tag
}

# Track event with user attributes and event tags
optimizely_client.track(event_key, user_id, attributes, event_tags)

# Track event with event tags and without user attributes
optimizely_client.track(event_key, user_id, nil, event_tags)
let attributes = ["device" : "iPhone", "ad_source" : "my_campaign"]

var eventTags = Dictionary<String, Any>()
eventTags["purchasePrice"] = 64.32
eventTags["category"] = "shoes"
eventTags["revenue"] = 6432  // reserved "revenue" tag
eventTags["value"] = 4 // reserved "value" tag

// Track event with user attributes and event tags
optimizely?.track("my_conversion",
                  userId:"user123",
                  attributes:attributes,
                  eventTags:eventTags)

Reserved tag keys

The following table lists the reserved tag keys, which are included in their corresponding fields in the Optimizely event API payload. They're bundled into event tags for your convenience. Use them if you want to benefit from seeing specific reporting features, such as revenue metrics or numeric metrics, on your Results page.

Tag key

Description

revenue

An integer value that is used to track the revenue metric for your experiments, aggregated across all conversion events. Note that:

  • Revenue is recorded in cents; to record a revenue value of $64.32, use 6432.
  • Add any event you want to track revenue for as a metric in your experiment.
    *Use the overall revenue metric to aggregate multiple metrics tracking separate revenue events. The overall revenue event won't track any revenue unless other metrics in your experiment are tracking an increase or decrease in total revenue; it won't work on its own.

value

A floating point value that is used to track a custom value for your experiments. Use this to pass the value for numeric metrics.

  • Note: We do not recommend using total value metrics to track monetary values.

Unlike revenue metrics, which use fixed-point numbers, numeric metrics use floating-point numbers. For example, $72.81 would be submitted as 7281 with revenue, but as 72.81 with value. Due to the dynamic precision of floating-point numbers, aggregations for numeric metrics are susceptible to rounding. When tracking monetary values, we recommend using the revenue tag to prevent these rounding errors.


Did this page help you?