Skip to content

Derived Metric Data Element

The Derived Metric data element runs a JavaScript snippet per event and writes a single computed value directly into the event's contextdata — no Rule B or Attach Data action required. The result is also available as a Launch data element for use in conditions and other action fields.

Screenshot needed

Capture: The Derived Metric data element UI in Launch, showing the name field, optional filter row, and code editor.

How it differs from other data elements

Type Sees Runs when Result lands at
Macro sharedState only Once at config load sharedState.airlock.<name>
Lookup Table event Per event sharedState.airlock.<name>
Accumulator event + history Per event sharedState.airlock.<name>
Derived Metric event + sharedState Per event contextdata[<name>] AND sharedState.airlock.<name>

The key difference is that Derived Metrics write directly to contextdata, so the value lands on the Analytics hit automatically without additional plumbing.

When to use it

Use a Derived Metric when:

  • You need a computed value that depends on both the current event and shared state
  • You want the result on the Analytics hit without an extra Rule B + Attach Data step
  • You want the same computation reused across multiple rules

Prefer other types when:

  • A static or single-source value is enough — use a Macro (config-time) or Lookup Table (event-time, no-code)
  • You need to maintain state across events — use an Accumulator
  • The computation modifies multiple fields or suppresses dispatch — use Evaluate JavaScript Rules

The script contract

Parameters: event (the track event data dictionary) and sharedState (snapshot of all extensions' shared state, including Airlock results from Lookup Tables and Accumulators).

Return value: Any scalar — string, number, or boolean. Returning null, undefined, or throwing skips the contextdata write for this event (fail-open — other metrics and the rule script are unaffected).

Setting it up

Step 1 — Define the metric in Extension Configuration

In Extension Configuration (Derived Metrics section), click Add derived metric:

  • Name — becomes the contextdata key (e.g. user_value_score → contextdata.user_value_score)
  • Filter (optional) — a path/value pair to restrict evaluation to matching events. Leave blank to evaluate on every event.
  • Script — the JavaScript snippet

Step 2 — Create the data element (optional)

If you need to reference the value in a Launch condition or action field:

  • Extension: Airlock
  • Data element type: Derived Metric
  • Metric: select from the dropdown

Step 3 — Reference the value

Three ways to use the result:

A — Automatically via contextdata. Because the value is written to contextdata.<name>, the Analytics extension picks it up with no extra steps. Map it to an eVar/prop in your Analytics processing rules using the contextdata key.

B — As a data element token. Use {%%Your Data Element Name%%} in any Launch field that accepts a token.

C — Inside a rule script. Read event.contextdata.<name> — Derived Metrics run before the rule script so the value is already present.

Worked example: user value score

Classify each event into "high", "medium", or "new" based on lifetime app launches and the current cart total.

Extension Configuration → Derived Metrics:

Field Value
Name user_value_score
Filter (blank — every event)
Script (see below) 
var launches = (sharedState.lifecycle
  && sharedState.lifecycle.lifecyclecontextdata
  && sharedState.lifecycle.lifecyclecontextdata.launches) || 0;
var cartTotal = parseFloat(
  event.contextdata && event.contextdata.cart_total || 0
);

if (launches > 20 && cartTotal > 100) return "high";
if (launches > 5) return "medium";
return "new";

Every event now arrives at Analytics with contextdata.user_value_score already set.

Evaluation order

Airlock resolves in this fixed order before dispatching the enriched event:

  1. Lookup Tables
  2. Accumulators
  3. Derived Metrics ← here
  4. Rule script (Evaluate JavaScript Rules)

A Derived Metric can read Lookup Table and Accumulator results via sharedState.airlock.<name>. A rule script can read Derived Metric results via event.contextdata.<name>.

Last-value retention

When a metric has a filter and the current event doesn't match, the metric keeps its last published value in both contextdata and shared state. This means downstream rules still see the previous result rather than an empty string.

If you want non-matching events to show no value, have the script return "" when the conditions aren't met rather than relying on the filter.

Error handling

Fail-open: if a metric's script throws or exceeds the 2-second timeout, that metric is skipped. Other metrics, the rule script, and the event dispatch are unaffected. The error is logged at debug level — check the device console or set the Log Level to debug in Extension Configuration.

Verifying with Assurance

  1. Connect the test app to Assurance.
  2. Fire a track event that should trigger the metric.
  3. Find the Airlock Processed Track event. Confirm contextdata.<name> is present with the expected value.
  4. For filtered metrics: fire one matching event, then one non-matching event, and confirm the non-matching hit carries the retained value.

Screenshot needed

Capture: Assurance showing the Airlock Processed Track event with the derived metric value visible in contextdata.

Common mistakes

The metric never appears in contextdata. The filter doesn't match. Check the filter path/value against the actual event payload in Assurance, or remove the filter while debugging.

Script always returns undefined. Forgot to return a value. Airlock treats a missing return as no value and skips the contextdata write.

event.contextdata is undefined inside the script. Some events don't include a contextdata block. Guard with event.contextdata && event.contextdata.foo.

See also