Setting Up the Segment Integration with Reactiv

Setup is deliberately light on your end. You create one credential in Segment (a Public API token) and enter it — plus your workspace's region — into a configuration form in your Reactiv dashboard. Reactiv does the rest automatically: it provisions the Segment source and write key for you. This guide walks through both places, including exactly where to find every value the form asks for.

Prerequisites

Before you begin, make sure you have:

• A Segment workspace (a Segment account with Connections enabled). A free workspace is fine to start.
• Permission to create a Public API token in that workspace — this generally means a Workspace Owner (or an account with access-management rights).
• Knowledge of your workspace's data region — US or EU. This is set when the workspace is created and can't be changed later; if you're unsure, check with whoever administers your Segment account.
• Access to your Reactiv dashboard with permission to manage integrations.

💡 You do not need to update your app or install a Segment SDK. Reactiv delivers events to Segment entirely server-side. There's no code change, no app-store release, and no client-side write key to manage.

How the Segment Integration Works

You provide a single Public API token; Reactiv uses it once, at install time, to set up the plumbing in your workspace. After that, events flow server-to-server.

Reactiv creates a dedicated HTTP API source in your workspace so its events are cleanly separated from anything else you send to Segment. The Public API token is only ever used during install and uninstall — never to send events — so its job is done once setup completes.

Step-by-Step Guide

Step 1: Create a Public API token in Segment

Reactiv needs a Segment Public API token to find-or-create its source and provision a write key in your workspace.

1. In the Segment web app, go to Settings → Access Management → Tokens.
2. Create a new token. Give it a recognizable name (e.g. Reactiv Integration).
3. Grant it Source read/write access to the workspace you want Reactiv to write to.
4. Copy the token. It starts with sgp_ — copy the whole value, including that prefix, with no truncation.

🔒 Treat the Public API token as a secret. You'll paste it into the Reactiv dashboard once; Reactiv stores it encrypted and uses it only during install and uninstall. Don't commit it to source control or share it elsewhere. You can revoke it in Segment at any time.

⚠️ The token needs Source read/write scope specifically. A token without it will fail at install with a scope error. "Source read/write" is a token scope in Access Management — it's not the same as the Track/Identify permissions attached to a write key.

Step 2: Confirm your workspace region

Segment workspaces are data-resident in either the US or the EU, and this determines which regional endpoints Reactiv must use. You'll select this region in the dashboard form in Step 3.

⚠️ Getting the region wrong fails silently. Segment discards events sent to the wrong region without returning an error — delivery appears to succeed on Reactiv's side while nothing arrives in your Segment debugger. Confirm your workspace's region before connecting. (As a safety net, Reactiv verifies your workspace's region live during install and self-corrects a wrong selection at that point — but a workspace whose region is entered incorrectly and never re-installed is the one case this can't catch.)

If you're not sure, ask your Segment administrator, or check your workspace's data residency in Segment's workspace settings.

Step 3: Connect the integration in your Reactiv dashboard

In your Reactiv dashboard, go to Integrations, select Segment, and fill in the configuration form:

When you save and enable the integration, Reactiv:

1. Verifies your token and region — it authenticates against Segment's Public API and confirms which region your workspace actually lives in, correcting the selection if needed.
2. Finds or creates the source — a dedicated HTTP API source named reactiv-<your-store> (derived from your store's .myshopify.com domain) is created if it doesn't already exist. Re-running setup reuses the same source — it won't create duplicates.
3. Provisions the write key — Reactiv reuses the write key Segment automatically attaches to the source. (In the rare case the source has none, Reactiv mints one.)
4. Starts streaming — supported events begin flowing into your workspace shortly after enablement.

If a check fails, the integration stays disabled and the dashboard shows an actionable error — for example, an invalid token or a missing scope. Fix the cause in Segment and enable again.

Where Do I Find My Credentials?

Public API Token

In the Segment web app, go to Settings → Access Management → Tokens and create a token with Source read/write access (Step 1). This is the only value you copy out of Segment. It's validated for format the moment you save the form, and verified live against Segment when the integration is enabled — an invalid or revoked token surfaces a clear error at that point.

Region

This isn't a value you copy from a Segment screen — it's simply which region your workspace was created in (US or EU). Confirm it with your Segment administrator or in your workspace's data-residency settings. Getting it wrong doesn't fail visibly at install; it fails silently at event-delivery time (see Step 2).

What about the source and write key?

You don't provide these — Reactiv provisions them for you during install and manages them for you. You'll see the source appear in Segment under Connections → Sources as reactiv-<your-store> once setup completes.

What Data Lands in Segment

Each Reactiv app event is delivered to your source as one or more standard Segment calls:

• identify — sent alongside an event only when the event carries a customer email, so Segment can attach the profile to the right user.
• track — the event itself, using a Segment event name (see the table below).
• screen — used for screen-view events instead of track.

Every call is attributed to a user: Reactiv includes a userId when the customer is known, or an anonymousId otherwise. An event with no identity of either kind can't be attributed and isn't sent.

Ecommerce spec mapping

For the core commerce events, Reactiv maps both the event name and its properties to the Segment Ecommerce Spec v2 — so fields like product_id, name, price, currency, products[], and revenue arrive in the shape downstream destinations expect. The original Reactiv fields are kept alongside the spec fields, so nothing is lost. Non-commerce events carry their Reactiv properties through as-is.

Supported events

Reactiv sends the following events. Any Reactiv event not listed here is not forwarded to Segment.

Additional Notes & Troubleshooting

Reactiv reports success, but no events show up in Segment. The most common cause is a region mismatch — Segment silently drops events sent to the wrong region. Confirm your workspace's region (US vs. EU) matches what's configured, and update it if needed. No re-provisioning is required; the region only controls which endpoint Reactiv calls.

Events worked before and suddenly stopped. The write key may have been revoked in Segment. If someone deleted or rotated the key on the reactiv-<your-store> source (Connections → Sources → [source] → Settings → API Keys), delivery starts failing. Re-running the Reactiv setup provisions a fresh key.

A brand-new connection sends events but they don't appear right away. If Reactiv had to mint a new write key (only when your source had none), Segment needs a short window — usually under a minute — to propagate it. Events sent in that window are accepted but may not reach the debugger. Wait a moment and re-test. When Reactiv reuses your source's existing key (the common case), there's no such delay.

A specific event type never appears. It may not be in the supported-events list above — unlisted Reactiv events aren't forwarded. If an event you need is missing, contact Reactiv support so it can be considered for a future release.

A specific event appears for some users but not others. Segment requires an identity on every call. An event that arrives with neither a known customer nor an anonymous ID can't be attributed and isn't sent. This is expected behavior, not a delivery failure.

Occasional events go missing in bursts. Any single call larger than 32 KB is dropped rather than failing the rest of its batch — usually caused by an unusually large properties payload. Contact Reactiv support if you see this consistently.

Install fails with a token error. An invalid or revoked token produces a token error; a token missing Source read/write scope produces a scope error. Create a new token in Segment (Settings → Access Management → Tokens) with the correct scope and re-enter it.

Disabling the integration never deletes your data. Uninstalling stops delivery but leaves your Segment source — and every event already delivered to it — intact. Reactiv only removes a write key on uninstall if Reactiv itself minted it; a key that already existed on your source is left in place.

Delivery is resilient. Transient Segment errors (rate limits, 5xx, network blips) are retried automatically before an event is considered failed. Persistent failures usually indicate a Segment-side incident — check Segment's status page.

Need help? Contact Reactiv support and include the dashboard error message (it never contains your token) and, if events are missing, whether anything appears in your Segment source's debugger.