Customer.io
Server-side event delivery to Customer.io via the official customerio-node SDK. Tracks events with TrackClient.track(), manages identities with identify(), and supports the full lifecycle: page views, device registration, suppress/unsuppress, profile merging, and transactional messaging via APIClient.sendEmail() / sendPush().
Customer.io is a server destination in the walkerOS flow:
Receives events server-side from the collector, resolves a `customerId` (or falls back to `anonymousId`), optionally fires `identify()`, then forwards the event to Customer.io for campaigns, broadcasts, and transactional messaging.
Installation
- Integrated
- Bundled
Configuration
This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.
Settings
| Property | Type | Description | More |
|---|---|---|---|
siteId | string | Customer.io Site ID. Find it in Settings > Workspace Settings > API Credentials. | |
apiKey | string | Customer.io API Key. Find it in Settings > Workspace Settings > API Credentials. | |
appApiKey | string | App API Key for transactional messaging (sendEmail/sendPush). Find it in Settings > Workspace Settings > API Credentials > App API Keys. | |
region | 'us' | 'eu' | Data center region. Must match where your Customer.io workspace was created. Default: us. | |
timeout | integer | HTTP request timeout in milliseconds. Default: 10000. | |
customerId | string | walkerOS mapping value path to resolve customerId from each event (like user.id). | |
anonymousId | string | walkerOS mapping value path to resolve anonymousId from each event (like user.session). | |
identify | any | Destination-level identity mapping. Resolves to { email?, first_name?, ... } attributes. Fires identify() on first push and re-fires when values change. |
Mapping
Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.
| Property | Type | Description | More |
|---|---|---|---|
identify | any | Per-event identify attributes. Resolves to { email?, first_name?, ... }. Use with skip: true on login/identify events. | |
page | any | Per-event page view. Resolves to { url, ... }. Calls trackPageView(). Use with skip: true. | |
destroy | boolean | Permanently delete person from Customer.io. Set true on delete events with skip: true. | |
suppress | boolean | Suppress person (stop messaging without deleting data). Set true with skip: true. | |
unsuppress | boolean | Unsuppress person (resume messaging). Set true with skip: true. | |
addDevice | any | Register push device. Resolves to { deviceId, platform, data? }. Use with skip: true. | |
deleteDevice | any | Remove push device. Resolves to { deviceId, platform }. Use with skip: true. | |
merge | any | Merge duplicate profiles. Resolves to { primaryType, primaryId, secondaryType, secondaryId }. Use with skip: true. | |
sendEmail | any | Send transactional email. Resolves to { to, transactional_message_id, message_data?, identifiers? }. Requires appApiKey. Use with skip: true. | |
sendPush | any | Send transactional push. Resolves to { transactional_message_id, message_data?, identifiers? }. Requires appApiKey. Use with skip: true. |
Examples
Anonymous track
When no customer id is resolved the event is sent via trackAnonymous keyed by the session id.
Default track
A walkerOS event is forwarded to Customer.io as a track call keyed by the user id.
Destination identify
Destination-level identify fires a Customer.io identify call once on the first push, before the track, attaching user attributes.
Destroy person
A user delete event permanently removes the person from Customer.io via trackClient.destroy.
Mapped properties
A data mapping transforms the event payload into Customer.io track properties for an order.
Rename event
A mapping rule renames the walker event to a Customer.io-specific event name such as purchase.
Page view
A page view fires trackPageView with the URL and referrer instead of a generic track call.
Suppress person
A user suppress event stops messaging for the person without deleting their profile data.
Unsuppress person
A user unsuppress event resumes messaging for a previously suppressed Customer.io profile.
User login identify
A user login triggers only a Customer.io identify call with profile attributes, skipping the track.
Identity is resolved automatically from each event: customerId defaults to user.id and anonymousId defaults to user.session. Customer.io requires a customerId or anonymousId per event. When customerId is missing, the destination automatically falls back to trackAnonymous() so anonymous visitor data is preserved.
Customer lifecycle
Per-rule mapping settings control which lifecycle methods are called in addition to the default track():
| Mapping Setting | SDK Call | Use For |
|---|---|---|
identify | identify() | Login, signup, profile updates |
page | trackPageView() | Page view events |
destroy | destroy() | GDPR delete / user removal |
suppress | suppress() | Stop messaging (keep data) |
unsuppress | unsuppress() | Resume messaging |
addDevice | addDevice() | Register push notification token |
deleteDevice | deleteDevice() | Remove push token |
merge | mergeCustomers() | Consolidate duplicate profiles |
Use skip: true on the rule to fire only the lifecycle call without tracking a second track() event.
Transactional messaging
Set settings.appApiKey to enable sendEmail / sendPush via Customer.io's App API. These mappings resolve to the full request body expected by the SDK.