A Connector is the mapping of a Formation event to a specific endpoint. Each connector contains a single mapping, however, you may choose to configure multiple connectors to send different events to the same endpoint.
An Event is a message, generated and deployed by Formation, that contains offer details for your customers. These events are triggered by either specific actions taken by customers or by the crossing of predetermined dates over the course of the offer period. These events are sent to the configured endpoints in real-time, and in some cases, more than one event will be transmitted for the same customer action.
|Achieved||Sent when your customer has made progress in their offer by completing an assigned step.|
|Activated||Sent when your customer has activated their offer.|
|Completed||Sent when your customer has completed all of their assigned steps.|
Sent at a predetermined time during the associated offer period.
Notifications are currently managed by Formation on your behalf. Please contact your Formation representative if you're interested in utilizing or adjusting default functionality.
|Progressed||Sent when your customer has made progress towards a cumulative offer but has not yet achieved a step.|
|Reward||Sent when your customer has completed a step that has an associated reward value.|
Event payloads are delivered to your desired destination (Kinesis Stream or API Location) in JSON format. You may optionally provide a jq transformation to create objects in your desired schema. All events contain the following top-level keys:
- type - which type from the table above this is. This enables you to send multiple event types to the same destination as each event type has slightly different characteristics.
- created - UTC timestamp for when the event was created.
Every connector event payload will also contain an offer object which will contain:
- customer_id - the identifier of the customer this notification pertains to.
- offer_type - what type of offer this notification pertains to (week streak, spend get, etc).
- unique_offer_id - the specific customer offer this notification pertains to.
- start_time - the local date & time that the offer starts.
- end_time - the local date & time that the offer ends.
- status - the current state of the offer (eligible, active, completed).
- steps - an array of objects describing the customer's specific offer.
- offer_reward - an object that describes the reward the customer will receive once all steps are completed in the offer.
- total_reward - an object that describes the sum of rewards the customer is eligible in the offer.
- tags - an array of user-entered key-value pairs entered in the platform interface before sending the offer to customers.
Each step object contains:
- conditions - what the customer must complete to achieve the step (spend, category purchase, required completion date, etc.)
- status - what the customer's status is on that particular step (eligible, completed)
- reward - an object that describes the reward the customer will receive for completing that step, if applicable
A reward object contains:
- reward_value - how much the customer will receive
- reward_currency - the type of reward the customer will receive
- reward_type - whether the reward is a fixed value or variable based on spend
Specific information regarding the fields and expected values for each offer type can be made available through your CSM upon request.