Custom events are designed to help you track any active or passive event or action related to a user that Iterable doesn't already track as a system event.
This article reviews how you can view and manage the fields (or properties) of custom events so that you can use them in your marketing campaigns.
NOTE
To learn more about custom events and how to create and track them, read Managing Custom Events.
In this article
Viewing custom event fields
Users who have the Manage Settings project permission can access the Data Schema Management screen to view and manage custom events.
To view the data fields for a custom event, find the event in the Data Schema Management page and click on its name. Here, you can see each event field, its data type, and when it was created.
id
Custom event When sending a custom event to Iterable via the POST /api/events/track
or POST /api/events/trackBulk
API endpoints, an optional string id
parameter may be passed.
If no id
is specified, then Iterable generates a value for the event's id
and includes it in the API response body. To update an event later, make sure
to provide an id
value or save the one that Iterable generates.
If an event exists with that id
, the event will be updated.
If you provide an id
value, it 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" } }
Including custom fields for an event
Event properties are different from user profile fields because they are not stored on the user profile. Instead, they are tied to the event.
If an event was used to trigger a campaign in a journey, then you can insert event properties using Handlebars. This includes additional custom fields.
You can nest custom fields as an array of key:value pairs in the dataFields
property when you use the following endpoints:
For example, if you are sending over an orderShipped
event, you may want to
include shippingAddress
and trackingUrl
as properties. This way, you can
dynamically insert these properties into a shipping confirmation email
template.
Suppose Iterable receives the following orderShipped
event and uses it to
trigger a shipping confirmation email in a journey:
{ "email": "ramona@example.com", "eventName": "orderShipped", "dataFields": { "shippingAddress": "929 Market Street, Suite 500, San Francisco, CA 94103", "trackingUrl": "iterable.com" } }
Using event properties to customize a template
You can dynamically insert event properties into a message with Handlebars. However, it's important to note that the event's fields are only available to the template when the campaign is triggered by the custom event.
For example, if an orderShipped
event includes a trackingUrl
property, you
can make a journey that's triggered when the orderShipped
event happens.
Next, add a journey step that sends a shipping confirmation email containing the
trackingUrl
to your user after their items have shipped.
This syntax will insert the actual tracking URL into the email template:
NOTE
Want to use event data in a template that isn't triggered by the event?
One way to do this is to make a subsequent API call to
POST /api/users/update
and include these properties nested the dataFields
for the user
object.
Any user property updated this way will always reflect the most recent value.
For example, with a repetitive event such as watchedMovie
, you could send a
user profile field of lastMovieWatched
, then you can use that property in
Handlebars for any template, not just a template triggered by the
watchedMovie
event.