Action Keys and Experiment Goals

Action keys are the measurement language for a custom website. They name things that happened: a lead was submitted, a product was added, a checkout started, a booking was requested. Page views are not actions: count them with Page Views.

Track an Action

Use key for action calls. The key is the action identifier used by SDK calls, filters, and reports.

await arky.actions.track({
key: "hero.cta.clicked",
data: {
  placement: "homepage",
},
});

Moments Arky Records Itself

Arky records some moments in the customer’s timeline on its own, typed, in the same save as the moment: cart_item_added, cart_item_removed, order_placed, form_submitted, support_conversation_started, support_conversation_escalated (handed to the team), support_conversation_resolved, customer_group_member_activated, customer_group_member_cancelled and customer_group_member_switched. Don’t track these from the storefront: they would count twice, and a custom action can’t use one of these keys. order_placed means an order was placed, paid or not.

arky.actions.track records custom actions only, such as the SDK’s common keys (product.view, booking_service.view, checkout.started, search, share) or your own. Each action belongs to the current customer and shows on their timeline in Admin.

Assign a Variant

Experiments are created in Admin under Experiments. A running experiment has:

• an experiment key, such as homepage_hero
• two to eight variants with keys and positive basis-point allocations totaling 10_000
• a goal action key, such as hero.cta.clicked
• an attribution window from 1 to 90 days

Create and edit the complete definition while it is a Draft, then start it explicitly. Starting needs the goal key to be one of Arky’s own action keys or a custom key the store has already tracked, so a misspelt key is refused with 409 EXPERIMENT.GOAL_NOT_TRACKED instead of silently counting nothing. A key tracked only moments ago is refused until search holds it; try again a moment later. The storefront call creates one durable assignment for the current customer, only while the experiment is running. Retries and later sessions for that customer return the same variant, also after the experiment is paused or completed. A missing experiment, or one that isn’t running and has no assignment for the customer, returns inactive, allowing the storefront to use its code-owned baseline.

An assignment means the storefront asked for a variant, so call use only where that variant is actually shown.

const experiment = await arky.experiments.use({ key: "homepage_hero" });

if (experiment.type === "assigned" && experiment.variant_key === "agency") {
renderAgencyHero();
} else {
renderBaselineHero();
}

Track The Goal

When the visitor performs the goal action, track that Action normally. Do not attach an experiment, assignment, version, or variant: Arky converts the customer’s assignment once, when an Action with the exact goal key is recorded inside the assignment’s attribution window.

await arky.actions.track({
key: "hero.cta.clicked",
data: {
  placement: "homepage",
},
});

Read Results

Admin shows descriptive results, counted exactly as assignments and goal Actions happen:

• eligible_assignments: unique assignments included in measurement
• converted_assignments: assignments with at least one qualifying goal Action
• observed_conversion_rate: converted divided by eligible assignments
• excluded_conflicting_customers: consolidation conflicts excluded from causal results
• result freshness, and open_windows: each variant’s eligible assignments whose attribution window is still open
• highest_observed: the largest raw rate, without claiming statistical significance or a winner

Pausing or completing an experiment only stops new assignments: customers already assigned keep their variant, and a goal counts inside its assignment’s window whatever the experiment’s status. Resuming preserves the original start and existing sticky assignments; completed experiments are terminal.