Integrate Rokt Calendar with Braze
Setup
Rokt Calendar is a dynamic calendar marketing technology that enables partners to push 1:1 events and promotional communications—in the form of calendar events and notifications—across a proprietary network of subscriber calendars. You can access Rokt Calendar’s services through a Braze webhook to send messages to your end users.
The integration allows Rokt Calendar subscribers and associated subscription data to be pushed into Braze, where this information is added to existing user profiles as custom attributes. If there is no match between the calendar subscriber and the Braze user, a new user is created in Braze.
You can use the Braze Canvas to define a journey that targets a segment of your audience. The calendar event is used as a communication method—the same way you might already be using SMS, email, and push notifications. Audience segmentation can be done based on any of the standard Braze user attributes, as well as custom attributes generated through the calendar subscription.
To define the content of the calendar event, you need to create a Braze webhook template. The template can then be used for the creation of the calendar event.
Read on for guidance on:
- General requirements
- Integration setup
- Webhook setup
- Generating calendar subscribers
- Using the webhook template (creating or defining an event)
Setup requirements
| Requirement | Origin | Who | Description |
|---|---|---|---|
| Rokt Calendar OAuth credentials | Rokt Calendar | Rokt Calendar account manager | Use these credentials to connect your Braze and Rokt Calendar accounts. It is set up for each new Braze client and added to Connected Content in Braze by going to:. Manage App Group > Connected Content > Add Credential |
| Rokt Calendar account | Rokt Calendar | Rokt Calendar account manager | A partner-specific Rokt Calendar account will be set up by an account manager. |
| Calendar setup | Rokt Calendar | Rokt Calendar account manager | A calendar will be set up to reflect business context and settings: - Merge flag - subscriberId fallback flag - Email capture, if needed |
| Webhook setup | Rokt Calendar | Rokt Calendar account manager | Add the Braze webhook type to the management center using: - Braze endpoint— https://rest.iad-01.braze.com- REST API key |
| External subscriberId | Partner | Partner | This is the identifier used by the Rokt Calendar subscription process to match the calendar subscriber with the Braze user. This is something that is passed through by the partner to Rokt Calendar. Email address can also be used. |
| Rest API key and permissions | Braze | Partner | Create a new API Key in Braze and provide this to your account manager. To create a new API key in Braze, go to: Developer Console > API Settings > Create New API Key and set permissions for users.track, users.alias.new and users.identify under the User Data heading. |
Integration
You use both your Rokt Calendar and Braze accounts to set up the Rokt Calendar integration. You need to set up two types of templates:
- Send new personalized event—allows new events to be added to a segment of subscribers’ calendars
- Update personalized event—allows for an update to be made to an event that has already been added to subscribers’ calendars
Template setup: send new personalized event
- Create a webhook template in Braze. You can create this from the Templates & Media section, or create a new webhook campaign in Braze. Select Blank Template.
- Fill out your template. To complete the template setup, configure the following:
- Settings
- Compose
Webhook settings
Configure the Request Headers and HTTP Method.
Request Headers
For Authorization, enter:
Bearer {% connected_content https://api.roktcalendar.com/oauth2/token :method post :basic_auth Rokt-Calendar-API :body grant_type=client_credentials :save token :retry %}{{token.access_token}}
This is the credential name in Manage App Group > Connected Content > Credential.
For Content-Type, enter "application/json".
HTTP Method
For HTTP Method, select Post.
Webhook compose {#webhook-compose}
Complete the setup by defining the Webhook URL and the content of the Request Body in the Compose tab.
Webhook URL
For Webhook URL, enter:
{% assign accountCode = {{custom_attribute.${rokt:account_code}}}[0] | split: '/' | first %}https://api.roktcalendar.com/v1/subscriptionevent/{{accountCode}}
Request Body
From the Request Body dropdown, select Raw Text.
In the Request Body text box enter:
{% capture eventId %}Event_0001{% endcapture %}
{% capture eventTitle %}Event Title{% endcapture %}
{% capture eventDescr %}Event Description{% endcapture %}
{% capture eventLocation %}Event Location{% endcapture %}
{% capture eventStart %}2019-02-21T15:00:00{% endcapture %}
{% capture eventEnd %}2019-02-21T15:00:00{% endcapture %}
{% capture notifyBefore %}15{% endcapture %}
{% capture eventTZ %}Eastern Standard Time{% endcapture %}
{% comment %} For a list of valid timezones see: https://roktcalendar-api.readme.io/docs/timezones {% endcomment %}
{
"event": {
"eventId": "{{eventId}}_{{${user_id}}}",
"title": "{{eventTitle}}",
"description": "{{eventDescr}}",
"location": "{{eventLocation}}",
"start": "{{eventStart}}",
"end": "{{eventEnd}}",
"timezone": "{{eventTZ}}",
"notifyBefore": "{{notifyBefore}}"
},
"subscriptionIds": ["{{custom_attribute.${rokt:subscription_id}| join: '","' }}"]
}
Template setup: update personalized event
- Create a webhook template in Braze. You can create this from the Templates & Media section, or create a new webhook campaign in Braze. Select Blank Template.
- Fill out your template. To complete the template setup, configure the following:
- Settings
- Compose
Webhook settings
Configure the Request Headers and HTTP Method.
Request Headers
For Authorization, enter:
Bearer {% connected_content https://api.roktcalendar.com/oauth2/token :method post :basic_auth Rokt-Calendar-API :body grant_type=client_credentials :save token :retry %}{{token.access_token}}
This is the credential name in Manage App Group > Connected Content > Credential.
For Content-Type, enter "application/json".
HTTP Method
For HTTP Method, select Post.
Webhook compose
Complete the setup by defining the Webhook URL and the content of the Request Body in the Compose tab.
Webhook URL
For Webhook URL, enter:
{% assign accountCode = {{custom_attribute.${rokt:account_code}}}[0] | split: '/' | first %}https://api.roktcalendar.com/v1/subscriptionevent/{{accountCode}}/update
Request Body
From the Request Body dropdown, select Raw Text.
In the Request Body text box enter:
{% capture eventId %}Event_0001{% endcapture %}
{% capture eventTitle %}Event Title{% endcapture %}
{% capture eventDescr %}Event Description{% endcapture %}
{% capture eventLocation %}Event Location{% endcapture %}
{% capture eventStart %}2019-02-21T15:00:00{% endcapture %}
{% capture eventEnd %}2019-02-21T15:00:00{% endcapture %}
{% capture notifyBefore %}15{% endcapture %}
{% capture eventTZ %}Eastern Standard Time{% endcapture %}
{% comment %} For a list of valid timezones see: https://roktcalendar-api.readme.io/docs/timezones {% endcomment %}
{
"event": {
"eventId": "{{eventId}}_{{${user_id}}}",
"title": "{{eventTitle}}",
"description": "{{eventDescr}}",
"location": "{{eventLocation}}",
"start": "{{eventStart}}",
"end": "{{eventEnd}}",
"timezone": "{{eventTZ}}",
"notifyBefore": "{{notifyBefore}}"
}
}
Using webhooks
Creating an event from a webhook template
Once you have created the webhook template, you’re nearly ready to start sending out calendar events and messaging. The fields below detail what can be customized at the event level.
| Field | Definition | Example value |
|---|---|---|
| eventId (required) | A unique identifier for the event to be added or updated | Event_00001 |
| eventTitle (required) | The title of the event as it would appear in the calendar | Summer Sale 2020 |
| eventDescr | The description of the event as it would appear in the calendar | The sale is on for 3 days, click this link www.mybusiness.com/sale to see the offers. |
| eventLocation | The location of the event as it would appear in the calendar; note that this is often used as a second call to action which is complementary to the eventTitle | Open the event to get 50% off |
| eventStart (required) | The start date and time of the event as it would appear in the calendar | 2020-02-21T15:00:00 |
| eventEnd (required) | The end date and time of the event as it would appear in the calendar | 2020-02-21T16:00:00 |
| eventTz (required) | The time zone of the event as it would appear in the calendar; the list of applicable time zones can be found here | Eastern Standard Time |
| notifyBefore (required) | The reminder time of the event as it would appear in the calendar, expressed in minutes | 15 |
Using subscription-related custom attributes for segmentation
You can only send calendar events to Braze users that have a Rokt Calendar subscription record stored against them in the custom attributes. These are noted in the table below and can be used to segment the audience.
| Custom Attribute | Definition | Example Value |
|---|---|---|
| rokt:account_code | Code of the Rokt Calendar account | brazetest/f5733866ade2 and brazetest/ff10919f1078 |
| rokt:account_id | ID of the Rokt Calendar account | d0ce4299-7d6c-4888-bfd8- c7e867a0fa6c/f5733866ade2 |
| rokt:account_name | Name of the Rokt Calendar account | Braze Test/f5733866ade2 |
| rokt:calendar_code | Code of the Rokt Calendar calendar | test-calendar-1/f5733866ade2 |
| rokt:calendar_id | ID of the Rokt Calendar calendar | 9a9007c7-f5a4-e811-b13c- 06424c4f2724/f5733866ade2 |
| rokt:calendar_title | Title of the Rokt Calendar calendar | Test Calendar 1/f5733866ade2 |
| rokt:country_code | Country code related to the created subscription | AU/f5733866ade2 |
| rokt:device_name | Device type related to the created subscription | Desktop/f5733866ade2 |
| rokt:geo_country | Country of origin related to the created subscription | Australia/f5733866ade2 |
| rokt:optIn1 | If the user has opted in to the first of two opt-ins related to the created subscription | True/f5733866ade2 |
| rokt:optIn2 | If the user has opted in to the second of two opt-ins related to the created subscription | True/f5733866ade2 |
| rokt:source | The source of the created subscription | brazetest.Rokt Calendarapp.com/f5733866ade2 |
| rokt:subscriber_email | The email address entered by the user during the subscription process | test@email.com/f5733866ade2 |
| rokt:subscription_id | The subscription ID—which serves as a unique identifier—related to the created subscription | 06423672-b6ba-4536-aa36- 70788a7a0a36 |
| rokt:subscription_method | Subscription method (e.g., webcal or Google) related to the created subscription | WebCal/f5733866ade2 |
| rokt:tags | Calendar tags used related to the created subscription | Test Calendar 1/All Teams/f5733866ade2 and Test Calendar 1/TeamI//f5733866ade2 |
Using calendar subscriptions
Using Rokt Calendar to build an audience of calendar subscribers
To send calendar events from the Braze Canvas using the Rokt Calendar integration, you must set up a calendar and have users subscribed to the calendar. To do this you need to inform your users where and how to subscribe to the calendar.
| Requirement | Origin | Who | Description |
|---|---|---|---|
| Rokt Calendar account setup | Rokt Calendar | Rokt Calendar account manager | A client specific Rokt Calendar account needs to be setup. Contact sales-calendar@rokt.com to speak with an account manager. |
| Calendar setup | Rokt Calendar | Rokt Calendar account manager | Work with a Rokt account manager to set up a calendar that meets the needs of your business. |
| Provide subscription integration points | Client | Client | To build an audience of calendar subscribers, you need to offer a destination that the user can navigate to and from where they can subscribe to the calendar. Examples of common subscription integration points include: - Add to calendar button on your website - Add to calendar button on your app - Add to calendar link in an email or SMS - Add to calendar link on social media Learn more. |
| Promote the calendar | Client | Client | You should consider promoting the calendar to your audience so that they know how to subscribe. Calendar promotion examples: - Posts on social media - Email newsletters and updates - Blog posts - In-app notifications Learn more. |
Rokt Calendar and Braze implementation guide
This document sets out to explain the interaction between Rokt Calendar and Braze with specific focus on the data flow from Rokt to Braze.
1. Generate and onboard calendar subscribers
To use the calendar as a communication channel within Braze, you must have an existing calendar subscriber audience. A Braze campaign can be used to generate calendar subscribers from your existing audience through email, SMS, push notification, or another channel. Make sure your message includes the benefits of the calendar and how to subscribe.
Listed in the table below are the available campaign communication methods:
| Method | Origin | Description |
|---|---|---|
| Braze | Send an email that explains the calendar subscription with a link directing the user to where they can subscribe to the calendar. | |
| SMS | Braze | Send an SMS that explains the calendar subscription with a link directing the user to where they can subscribe to the calendar. |
| Push notification | Braze | Send a push notification that explains the calendar subscription with a link directing the user to where they can subscribe to the calendar. |
Then, once the audience exists, you can start using the calendar as a communication channel.
Where and how to subscribe
Your existing audience member needs to be directed to where they can subscribe to the relevant calendar. Your Braze and Rokt Calendar account managers can work together to assess the context of your business and determine the most appropriate subscription integration method.
Subscription integration methods
Listed in the table below are the various ways for an audience member to subscribe to a calendar.
| Integration method | System | Contact | Description |
|---|---|---|---|
| Rokt Calendar SmartCal page | Rokt Calendar | Rokt Calendar account manager | - Hosted by Rokt—no setup required - Embedded into a page on your website—minimal setup required |
| Rokt placement | Rokt | Rokt account manager | The placement offers add to calendar functionality, enabling the user to subscribe to the relevant calendar. The Rokt placement can be presented: - Pre-transaction - Post-transaction - Independently of a transaction as a standalone option (i.e., on a product page) This requires adding the Rokt tag to your website and ensuring the relevant data is passed. |
| Rokt Calendar API | Braze | Braze account manager | This requires integration work from your development team. |
Matching calendar subscribers to Braze users
When a new calendar subscriber is generated through your chosen integration, the subscription data is sent to Braze. A critical piece of the Rokt Calendar and Braze integration is the ability to assign subscription data to a Braze user, if the user exists. Matching is done based on a unique identifier common to a calendar subscription, which is added during the subscription process. This identifier is determined by you, based on how you identify users in Braze. If there is no match between the calendar subscriber and the Braze user, a new user is created in Braze.
Integration scenarios
The possible scenarios are discussed below.
| Context | Subscriber vs. user | Requirements |
|---|---|---|
| You are an existing Rokt Calendar and Braze client. Specifically, your calendar has subscribers and your Braze account has users that pre-date the use of the Braze integration (i.e., client has independent existing relationships with both Rokt Calendar and Braze). | - Calendar subscribers exist - Braze users exist | - Matching an identifier at the subscription level to Braze user identifier (e.g., email). - A data transfer of subscription data from Rokt Calendar to Braze user profile before go-live. |
| You are an existing Braze customer. Specifically, you do not use Rokt Calendar and your Braze account has existing users (i.e., client has an existing relationship with Braze only). | - No calendar subscribers - Braze users exist | As the subscribers are new, an agreed identifier—common to Braze users—is used. |
| You are not a Rokt Calendar or Braze client. Specifically, the calendar has no subscribers and the Braze account has no users that pre-date the use of the Braze integration (i.e., client has no existing relationship with Braze or Rokt Calendar). | - No calendar subscribers - No Braze users | As both calendar subscribers and Braze users are net new, an agreed identifier is assigned to the calendar subscription and Braze user. |
Choosing a unique subscriber identifier
A subscriber ID is used to uniquely identify the subscriber when they are created and subsequently flow through to other systems like Braze. The subscriber ID can be passed through during the subscription process by appending the subscriber ID to the calendar URL, for example mycal.calreplyapp.com/calendar1?subscriberid=1938d736.
Note that the subscriber ID is easily appended to the calendar URL if the client is launching the calendar page on their own asset where the user is known, usually through a logged-in or known user experience. If the user is not logged in—i.e., not known—then you can use the email capture functionality for the calendar, which allows the subscriber to enter an email as part of the subscription process. This then becomes the subscriber ID and is used to match a subscriber to a record in another system.
Data matching results
| Results | Details |
|---|---|
| Match exists | A match exists between calendar subscriber and Braze user profile. The subscription data is added to the Braze user profile. |
| No match exists | No match exists between calendar subscriber and Braze contact. A new Braze user profile is created and the subscription data is added. |
2. Audience segmentation in Braze
Use the filter tool to segment your audience when configuring a Braze campaign. Segmentations can include standard profile attributes or custom attributes for subscription-related data.
3. Sending a calendar event as a communication method
Creating a new event
You can send a calendar event as a communication method in Braze by following these steps:
- Create a new Canvas.
- Define the steps in the journey.
- Set the message channel as Webhook.
- Choose the Rokt Calendar webhook template for creating new events.
- Edit the webhook to define the following:
- Event ID (must be unique for each event)
- Event title
- Event location
- Event description
- Event start/end date and time
- Event reminder minutes
- Start the Canvas.
Once Braze reaches the step in the journey where the calendar event is sent out, the Braze webhook communicates with Rokt Calendar to add an event to the calendars of the users' who are part of the audience.
Updating a calendar event
You may want to update an existing calendar event that has already been sent out to subscribers.
- Create a new Canvas.
- Define the steps in the journey.
- Set the message channel as Webhook.
- Choose the Rokt Calendar webhook template for updating events.
- Edit the webhook to define the following:
- Event ID (ID of the event that you want to update)
- Event title
- Event location
- Event description
- Event start / end date and time
- Event reminder minutes
- Launch the Canvas.
Once Braze reaches the step in the journey where the calendar event is sent out, the Braze webhook communicates with Rokt Calendar to update the calendars of the users' who are part of the audience as defined by the segmentation.
4. Calendar reminders and optimizing the lock screen
Rokt Calendar technology is built on top of calendaring products that already exist (Google and Apple)—providing full access into a user's calendar at the point of subscription. As opposed to a push notification—which can be turned off at the point of site visit or app download—calendar reminders are on by default across device, granting 100% visibility on the lock screen at all times.
The purpose of the reminder is to alert a user than an event is beginning as well as to prompt the user to take some type of follow-up action. The styling of the reminder is device specific. The content of the reminder, which is a combination of the event title and location, determines how effective the user engagement is. Below is an example of the user experience:
5. Performance measurement
You can gain an understanding of how well your calendar communications are doing through performance measurement. Performance measurement takes into account two types of data: subscription data—which lives in Rokt Calendar—and engagement data—which lives in a variety of places. You can reach out to your account manager to further define reporting requirements and schedules.
| Data type | Source | Details |
|---|---|---|
| Subscription data | Rokt Calendar | - Subscription created - Individual events added (coming soon) - Individual events removed (coming soon) - Individual events updated (coming soon) - Unsubscribe (whole calendar) |
| Engagement data | Rokt Calendar, client’s analytics | - Rokt Calendar engagement calculation - Trackable links (client defined) |
| Journey performance | Braze | Braze journey analytics |
Support
If you have any questions, reach out to:
- Rokt Calendar sales support—calendar-sales@rokt.com
- Rokt Calendar tech support—calendar-support@rokt.com
- Braze support—support@braze.com