Use the API to programatically create a calendar subscription using the Webcal protocol
This API function requires that your application be authenticated via OAuth. You can learn how to authenticate your application here.
calendarParams
| Name | Type | Description |
|---|---|---|
| subscriberId Optional | String | Identifier that represents a unique user to you. E.g. email address, device id, anonymous id. |
| emailAddress Optional | String | Email address linked to the subscription. Rokt Calendar allows you to capture the the email address of a subscriber so that you can market to the subscriber at a later date. |
| additionalOptIn Optional | Boolean | Additional opt-in allows the subscriber to specify if they are opting-in to the question/statement as defined by the copy associated with the checkbox. |
| calendarTags Optional | CalendarTags[] | Array of calendar tags to filter events by. Tags are used to group similar events. For example all events that belong to the same sporting team/topic can be tagged with a team name. When a tagId is used, the subscription will only include events tagged with the selected tag. See Calendar Tag Model for complete schema. |
| timezoneId Optional | String | Windows timezone identifier to filter events by. If used, the subscription will include events that are tagged with this time zone and any events that are not tagged with a time zone. See Timezones for available list. |
| requestEventIds Optional | String[] (UUID/GUID) | An array of event identifiers. Identifiers that do not match will be ignored. |
| externalEventIds Optional | String[] | One or more identifiers that represents unique events to you. Identifiers that do not match will be ignored. |
| utmSource Optional | String | Value used to identify the referring subscriber Source. This is used as the UTM Source in Dashboard Analytics. e.g. Newsletter-December. |
| utmMedium Optional | String | Value used to identify the referring subscriber Medium. This is used as the UTM Source in Dashboard Analytics. e.g. Email |
| utmCampaign Optional | String | Value used to identify the referring subscriber Campaign. in Dashboard Analytics. e.g. Summer Campaign |
| utmContent Optional | String | Value used to identify the referring subscriber Content. Used for Dashboard Analytics. in Dashboard Analytics. e.g. 400x300 banner |
| userAgent Optional | String | The user agent string extracted from the Http header of the API request. This is used to identify the users operating system, device and other important parameters. |
| urlReferrer Optional | String | Url referrer of the user. Used for Dashboard Analytics. The place from which the subscriber navigated to the calendar page. e.g. Facebook |
| ipAddress Optional | String | IP Address of the user. Used for monitoring and logging purposes |
| events Optional | EventDetails[] | You can add manual events to this subscription that belong solely to this subscription. |
Protected Calendars
Rokt Calendar supports the ability to mark calendars as protected. Calendars can be marked as protected by emailing [email protected] with a special request.
Protected calendars have the following properties:
- Protected calendars are hidden and are not accessible via a public calendar URL
- Subscribing to a protected calendar must occur via the Rokt Calendar API
- Protected calendars require basic http authentication. Forcing basic authentication ensures that webcal URLs on iOS devices cannot be shared since the webcal password is masked after a user subscribes from an in-app experience.
Protected calendars require that the calendarParams object contains the username field. For iOS users, the username will appear under the Subscribe Calendar Information section, and the password will be randomly generated and masked.
Here is an example:
.png "CalReply_WebAPI_2.0.pdf-(page-9-of-10).png")
Returns
A webcal URL containing a subscriptionId as a GUID. The subscription ID is a unique subscription identifier.
Protected calendars return a webcal URL containing a subscriptionId as a GUID, prefixed with the username and password required for basic http authentication. The URL for a protected calendar will contain a randomly generated username and password as part of the url in the format of {username}:{password}.
The webcal subscription API function should be used to add new calendar subscription on iOS devices and for Microsoft Outlook users. This function is not compatible with Google Calendar.
Recommendation
It is recommended that you extract this GUID from the URL returned and store it against the users profile information in your own database.
Tip
To deactivate subscribers please see the information in this section Deactivate an Existing Subscription