On the project settings page, use the Manage Custom Events section to control how custom events flow into Iterable. You may find this functionality useful if using a platform like Segment to pass events into Iterable, and it’s passing in events that you don’t need.
In general, send events to Iterable only if they:
- Trigger a workflow
- Are useful for segmentation purposes (now or in the future)
This includes events that are misnamed or no longer relevant. The main downside to sending all events is that it can clutter segmentation and other workspaces, making it harder for both experienced users and newcomers to find the fields that they're looking for. This can also have a performance impact, as it may take longer for Iterable to return all of the possible fields to you.
Table of contents
Event handling options
For each incoming event, Iterable can:
- Save the event to a user's event history (useful for later segmentation)
- Trigger a workflow
- Save the event to a user's event history and trigger a workflow
- Do nothing
The below table shows an example configuration where Iterable ignores all
incoming error_app_crash
events, saves quizCompleted
events, and triggers
one or more workflows with signUp
events.
This example does not save signUp
events to users' event histories.
NOTE
Because quizCompleted
events are allowed, they have the potential to
trigger workflows, but Trigger Workflows is not selected in this example
because the event has not been listed as the trigger in any existing
workflows.
Event handling for newly encountered events
The Allow New Custom Events into the System toggle determines how an Iterable project deals with incoming custom events:
- When the toggle is on, the project saves all incoming events regardless of their event names. Additionally, it adds newly encountered events to the Existing Custom Events table (below the toggle), selecting both Allowed and Saved. This is the default behavior.
- When the toggle is off, the project only saves incoming events listed as Saved in the Existing Custom Events table (because they've been previously seen or you've manually added them).
NOTE
Disabling the Allow New Custom Events into the System toggle does not prevent Iterable from storing never-before-seen data fields on custom events that the project still allows. The toggle controls the top-level event names that Iterable stores, not the fields on those events.
Adding Events to the custom events list
In order to add a new event to the custom events table, navigate to the Existing Custom Events section and click New Custom Event.
Enter your desired event name in the Custom Event Name field that's presented to you, and click OK. Remember when entering the name that event names are case sensitive!
Notice how your new event is created with Allowed and Saved selected by default.
If you have already created a workflow that triggers off of the event (like below), then the Triggers Workflows checkbox will be selected as well.
With your new event now established, navigate to the space to the far right of the event, and click Edit to adjust how it will be treated in your environment.
NOTE
This screenshot assumes that the surveyCompleted
workflow exists.
While editing, you can decide if you want to allow the event to pass through, and if so, if you want it to be saved to a user's event history.
Here are some additional considerations:
- You cannot save an event to a user's event history without also allowing the event
- You cannot trigger a workflow from an event that is not allowed
- You cannot disallow an event that triggers a workflow without first dropping it as the trigger to that workflow
- An event cannot be deleted from the custom events table
- Allowing an event that was previously disallowed will not backfill or restore event history
Updating custom events
When sending a custom event to Iterable via the POST /events/track
API endpoint, an optional string id
parameter may be passed. If an event
exists with that id
, the event will be updated. If no id
is specified, a
new id
will automatically be generated and returned.
NOTE
An id
value must:
- Contain only alphanumeric characters and hyphens.
- Be no longer than 512 bytes in length.
- Be unique across all custom events in the project.
Sample response where an id
of "12345"
is passed in the track request:
{ "msg": "Event with id: 12345 tracked.", "code": "Success", "params": { "id": "12345" } }}
Sample response when no id
is passed in the track request:
{ "msg": "Event with id: 1397b147db9c41f187a39844beba9c tracked.", "code": "Success", "params": { "id": "1397b147db9c41f187a39844beba9c" } }
NOTE
The generated id
is only available from the POST /events/track
API response body and should be stored for use in subsequent event updates.
Comments
0 comments
Article is closed for comments.