Bloomreach — Track Event¶
Bloomreach Engagement (formerly Exponea) is a customer data and marketing automation platform. Use Bloomreach Engagement to create personalized customer experiences across multiple channels.
Track one Bloomreach Engagement customer event for a customer as soon as a real-time journey reaches an Activate node, using the Tracking API batch commands endpoint. Amperity tracks one event for each send, so that a Bloomreach Engagement scenario whose On event trigger listens for the event type can start for the customer, subject to its own conditions. See scenario triggers in the Bloomreach Engagement documentation.
The same request can also update properties on the customer’s profile. To send customer profiles and segment membership from a scheduled query or segment rather than in real time, use the Bloomreach destination.
This connector sends from a real-time journey. See Real-time destinations.
Beta
The Bloomreach — Track Event connector is in beta. Contact your Amperity representative to learn more.
Requirements¶
A private API key for the Bloomreach Engagement project that receives the events, whose API group has the Events > Set permission, and also Customer properties > Set when an Activate node maps customer properties. See add event and authentication in the Bloomreach Engagement documentation. These permissions can be limited to particular event types and properties, so a key set up for the Bloomreach destination may need Events > Set for the event types that this connector tracks. The connection test does not check these permissions.
A Bloomreach Engagement scenario whose On event trigger listens for the event type that you enter on the Activate node. Amperity tracks the event; it does not create the scenario, and it does not check that any scenario listens for the event type.
Credentials¶
This connector uses the “bloomreach” credential type, the same one that the Bloomreach destination uses, so a credential set up for that destination can be selected here. This connector uses the credential’s API base URL, project token, API key ID, and API secret. It does not use the External segments integration ID or access key.
Name and description
The name and description for a credential.
API base URL
The API base URL for your Bloomreach Engagement project.
Project token
The project token for your Bloomreach Engagement project.
API key ID
The public API key ID for your Bloomreach Engagement project.
API secret
The private API secret for your Bloomreach Engagement project. The API key’s API group needs Events > Set, and Customer properties > Set when an Activate node maps customer properties. This connector does not use import permissions.
You can find the API base URL and project token in your Bloomreach Engagement project settings. The API key ID and API secret are available in the API access section of your project settings.
Amperity sends each request to the API base URL with HTTP Basic authentication, using the API key ID and API secret, and names the project by its project token in the request path.
When you save the destination, Amperity tests the connection by reading the project’s time from GET /track/v2/projects/{project token}/system/time. The request tracks no event and changes nothing. It confirms the API base URL, project token, API key ID, and API secret, but not the Events > Set or Customer properties > Set permission, because neither is needed to read the time. A failed test reports the same messages as a failed send, as described under Failed sends: for example, a 401 or 403 reports a credential error and asks you to check the four credential values and the API group’s permissions.
Settings¶
Name and description
The name and description for a destination.
Business user access
By default a destination is available to all users who have permission to view personally identifiable information (PII).
Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies.
Enable the PII setting checkbox to allow limited access to PII for this destination.
Use the Restrict PII access policy option to prevent users from viewing data marked as PII anywhere in Amperity and from sending data to downstream workflows.
This connector has no other destination settings. Everything else is configured on the Activate node.
Activate node settings¶
The rest of the configuration for this connector belongs to the journey that sends to it. Add this destination to an Activate node, then configure the following fields on the node’s Payload tab. Two nodes may send to the same destination with different event types and identifiers. Attributes mapped in Event properties and Customer properties are set once for the destination in the journey, so every node that sends to it sends the same mapped attributes.
Event type
Required. The event type that your Bloomreach Engagement scenario’s On event trigger listens for. Amperity has no list of event types to choose from, so enter the exact event type. Amperity sends it exactly as entered, without changing its case or removing spaces: “Order Shipped” and “order_shipped” are sent as two different event types. Amperity does not send an event whose type is longer than 255 bytes, counted in UTF-8.
Bloomreach identifier
The name of the Bloomreach Engagement customer ID that Identifier attribute holds, such as “registered” or “email”, entered exactly as your Bloomreach Engagement project lists it under Administration > Identifiers. Amperity sends the customer’s identifier under this name in the event’s “customer_ids” object. Defaults to “registered”, which Amperity also uses when a node has no value for this field. Amperity does not check that the project defines the name, and an event sent under a name that the project does not define is not stored, as described under Failed sends.
Identifier attribute
Required. The Amperity attribute that holds the customer’s ID of the kind named above. Amperity sends a text value unchanged, and a whole number as text; it does not trim, normalize, or look up the value. See add event for the customer IDs Bloomreach Engagement accepts. An ID that matches no Bloomreach Engagement customer creates a new customer. A customer with no value for the attribute is not sent: there is no fallback to the Amperity ID. Other values that Amperity does not send are listed under Checked before sending.
Event properties
Optional. The properties tracked with this event, for the scenario’s conditions and personalization. A scenario reads an event property as {{ event.<name> }}. Select Edit to map Amperity attributes to property names on the Attributes tab, or to add fixed values on the Custom attributes tab. Amperity sends them in the event’s “properties” object, using each property name exactly as entered, including case. When there are no event properties, Amperity sends an empty “properties” object.
Customer properties
Optional. Properties that Amperity writes to the customer’s profile in the same request as the event, mapped the same way as Event properties. Amperity sends them as a separate customer update, keyed on the same customer ID, with the event’s timestamp as the update’s timestamp. When there are no customer properties, Amperity sends the event alone. Amperity does not control whether Bloomreach Engagement applies the customer update before or after it tracks the event, so put any value that the scenario needs when it starts in Event properties.
For both groups, Amperity sends each value with its type, and does not check or convert it: text, numbers, true or false values, nested values, and lists are sent as they are. Date values are sent as “YYYY-MM-DD” text. An attribute that the customer’s profile has with no value (null) is sent as null. An attribute that the profile does not have, or an enriched or custom attribute with no value, is left out. See add event for the property values Bloomreach Engagement accepts.
Request body¶
Amperity sends each send as one request to POST /track/v2/projects/{project token}/batch, holding one or two commands: the event, and the customer update when the node maps customer properties. The event’s “timestamp” is the time the journey queued the send, as Unix time in seconds with a fraction to the microsecond. Every attempt for the same send carries the same timestamp.
For example, with Event type set to “order_shipped”, Bloomreach identifier set to “registered”, an event property named “order_id”, and a customer property named “loyalty_tier”, Amperity sends:
{
"commands": [
{
"name": "customers/events",
"data": {
"customer_ids": {
"registered": "customer-123"
},
"event_type": "order_shipped",
"timestamp": 1793959240.123456,
"properties": {
"order_id": "A-1001"
}
}
},
{
"name": "customers",
"data": {
"customer_ids": {
"registered": "customer-123"
},
"properties": {
"loyalty_tier": "gold"
},
"update_timestamp": 1793959240.123456
}
}
]
}
Checked before sending¶
Before it sends a request, Amperity checks it against the following rules, and no others. When a check fails, Amperity sends nothing, and the send fails without another attempt. The failure message names the node field or the attribute to fix. Amperity reports the first of these that applies:
The event type is blank, or is longer than 255 bytes in UTF-8.
The customer has no value for the identifier attribute, or the value is blank.
The identifier is neither text nor a whole number, such as a decimal number or a list.
The identifier has no letter or digit, in any language, or is “null” or “undefined” in any combination of upper and lower case.
The event has more than 255 event properties.
The customer update has more than 255 customer properties.
The event, or the customer update, is larger than 972,800 bytes, measured once it is encoded as JSON.
The first is a problem with the node’s settings, and fails every send from that node until it is fixed. The others are problems with one customer’s data, and fail only that customer’s send.
A request that passes these checks can still be refused by Bloomreach Engagement, as described under Failed sends.
Failed sends¶
Amperity makes up to three attempts at each send. Each new attempt is scheduled between 200 and 700 milliseconds after the previous one fails, with no backoff. Within an attempt, Amperity sends the request once, except when Bloomreach Engagement answers with 429, as described below. A send that is not rate limited makes all three attempts within a few seconds.
How Amperity handles each failure:
401 or 403, or a 400 saying that the request could not be authenticated or that the project ID is invalid. The send fails without another attempt. Check the API base URL, project token, API key ID, and API secret, and that the API key’s API group has Events > Set, and Customer properties > Set when the node maps customer properties. A credential that Bloomreach Engagement refuses fails every send until it is fixed. Amperity reuses its connection to Bloomreach Engagement for each credential for up to 20 minutes, so after you edit the credential, sends can keep using the old values for up to 20 minutes. Choosing a different credential for the destination takes effect at once.
429. Amperity waits and sends the request again within the same attempt: after 1 second and then after 2 seconds, or after the time that Bloomreach Engagement gives in seconds in its “Retry-After” header when that is 10 seconds or less. If Bloomreach Engagement still answers with 429, or asks for a longer wait, Amperity makes another attempt, up to three in all.
408 or a server error (500 or higher). Amperity makes another attempt, up to three in all.
Any other 400. The send fails without another attempt.
Any other status, such as 404. The send fails without another attempt. Check that the API base URL is your project’s API base URL.
The API base URL’s host name cannot be resolved. Amperity makes another attempt, up to three in all. If every attempt fails, check the API base URL.
No answer, such as a timeout or a dropped connection. Amperity makes another attempt, up to three in all.
Bloomreach Engagement can also answer a request with success and report, for each command, whether it was accepted:
The event is refused. The event is not tracked, and the send fails without another attempt.
Only the customer update is refused. The event is tracked, but the send is reported as failed, without another attempt, because another attempt would track the event again.
A command is refused as not authorized. The send fails as a credential error, without another attempt. Check that the API key’s Events > Set permission covers this event type, and that its Customer properties > Set permission covers these customer properties.
The answer does not report on every command. The send fails without another attempt, because Amperity cannot tell whether the event was tracked.
Any other failure is reported as an unexpected error, and the send fails without another attempt. When Bloomreach Engagement gives a reason for a failure, the failure message includes it.
A failed send and its failure message appear in two places:
The Recent failures table on the Profile sends tab of the Destinations page. The tab is available when real-time profiles are enabled for your tenant.
The Activations tab of the customer’s profile, which also shows the send’s Attempt count, such as “3 / max 3”.
Amperity keeps only the failure message from the last attempt. A failed send cannot be retried from Amperity.
Amperity sends no deduplication key with a Bloomreach Engagement event. Every attempt for a send carries the same timestamp and properties, so when Bloomreach Engagement tracked an event but answered with 408 or a server error, or its answer did not reach Amperity, the next attempt sends an identical event. Bloomreach Engagement stores the repeated event once, but it starts scenarios before it removes duplicates, so the scenario can start again for the same send. See event deduplication . A scenario that must act at most once for each send can use a frequency condition after its On event trigger.
Amperity reports the send as successful when Bloomreach Engagement accepts every command in the request. Amperity does not check whether Bloomreach Engagement stored the event, whether the identifier matches an existing customer, or whether a scenario started.
Caution
Bloomreach Engagement answers some requests with success and then does not store what they sent, so Amperity reports these sends as successful:
The project does not define the name entered in Bloomreach identifier.
The event would add a property name to an event type that already has 255 distinct property names in the project. Keep the property names that each event type sends the same from send to send.
The customer update would add a customer property name to a project that already has 255 distinct customer property names. The event is still tracked, but the customer update is not stored.
The project’s Data Manager does not allow new event types, and the event type is new to the project. Add the event type in Data Manager before the journey goes live. See tracking API error messages .
Amperity limits how quickly it sends requests to Bloomreach Engagement with each credential.