Overview
The SundaySky API enables you to securely render and embed personalized videos in real time.
The API is used to POST data fields in JSON format (for example: first name and customer type) to SundaySky's API endpoint. SundaySky then creates a video in real time and returns a base64 string as the response that is used to play a personalized video for a viewer, using the SundaySky player.
Alternatively, you can decode the base64 response and extract different components of the video—such as the video stream URL or captions file URL—and use those components with third-party video players. When the video is played in a non-SundaySky player, SundaySky-specific functions such as clickable CTAs and analytics are not available.
The SundaySky API integration method is completely storage-less, meaning that any data used for personalization is completely purged after the video is generated.
In this end-to-end article, you will find comprehensive guidelines for using the SundaySky API, beginning with setting up a data library and concluding with generating video links for your viewers.
Note:
The SundaySky landing page builder cannot be used together with the SundaySky API. If you want to use the landing page builder, you will need to use a different data connector.
Step 1: Select or Create a Data Library
Based on how you want to personalize your video, you'll need to connect the video to a data library that includes the data fields for creating the personalization. SundaySky supports three methods of personalization: using a personalization token, message by audience, and show/skip scene.
- For on-screen text personalization, you only need to add data fields.
- For voice-over, message by audience, and show/skip scene, you need to have data fields in the data library along with their respective values.
For example: the data field department is added, along with its values: Finance, HR, and Marketing.
Before creating a new data library, we recommend that you review the existing data libraries in your account to see if one of them matches your requirements as the same data library can be used for multiple videos. If you are selecting an existing data library, it needs to meet the following conditions:
- The data fields in the library are those that you require for personalization. More data fields can always be added.
- The data library is connected to the SundaySky API data connector.
If you find a data library that has the data fields that you need but the library's data connector is not SundaySky API, do not change the library's data connector as this will negatively impact existing videos that use the connector. In such a case, you will need to create a new data library.
To learn how to select an existing library, see Selecting an Existing Data Library.
If you need to create a new library from scratch, see Creating a New Data Library.
At the end of Step 1:
A data library is selected for the video. This can be an existing data library or a new one.
Step 2: Select the SundaySky API Data Connector
| If you selected a data library that is already connected to the SundaySky API data connector, skip to Step 3. |
The connector is what enables the connection between the data fields that you defined in the data library and the actual viewer data you share via the SundaySky API.
| 1. |
Open the relevant video in the Studio. |
| 2. |
Select Data in the sidebar. |
| 3. |
Click Select in the data connector section. |
|
|
|
| 4. |
Select the SundaySky API data connector and then click Select at the bottom of the window. |
|
|
|
|
The data connector is attached to the library and the following message is displayed: |
|
|
|
|
| 5. |
Click Edit Mapped Fields to continue directly to field mapping. |
|
|
At the end of Step 2:
The SundaySky API data connector is attached to the data library.
Step 3: Review the Mapping of the Data Fields
| If you selected an existing data library whose data fields have already been mapped correctly, skip to Step 4. |
The mapping process specifies which property in the JSON that you post to the SundaySky API corresponds to the data field in the SundaySky data library. A precise mapping ensures that the right data is pulled from your database to populate a personalized video.
For additional guidelines, refer to the notes for Step 3 below.
| 1. |
Open the relevant video in the Studio. |
| 2. |
Select Data in the sidebar. |
| 3. |
Click Map Fields in the data connector section. |
|
|
|
|
In the mapping window, the data source field (JSON Field Name) is populated automatically according to the data field name. |
|
|
|
|
| 4. |
Review each JSON field name and, if required, edit it so that it exactly matches the JSON field in your data source. |
| 5. | (Optional) If you make any changes while reviewing the field mapping, click Save at the bottom of the window. |
- If you rename a data field after the mapping process, the JSON field name is not changed. A name change does not impact the existing mapping.
- If you add a data field after the initial mapping process, it is important to map it according to the guidelines above.
At the end of Step 3:
Each JSON field name is reviewed and edited so that it exactly matches the corresponding JSON key in your database.
Step 4: Configure the Content
Now that you've set up your data library, you can configure the content in the video's scenes using the data fields.
The on-screen text, voice-over, and media can be personalized using either a personalization token or audience messaging. In addition, you can also define that a specific scene will be shown or skipped according to an audience segment.
In the example below, a personalization token is used to customize the text according to the first name of the person watching the video.
In the following articles, you'll find step-by-step instructions on how to configure the different types of content:
Configuring Text with a Personalization Token
Configuring Text According to Audience
Configuring a Voice-over with a Personalization Token
Configuring a Voice-over According to Audience
Configuring Media According to a Data Stream
Configuring Media According to Audience
Showing or Skipping a Scene by Audience
At the end of Step 4:
All the relevant content in the video is configured according to the desired personalization.
Step 5: Approve the Video
After you have finished creating the video—including the configuration of all the personalized content—we recommend that you preview the video using viewer profiles to make sure that it looks exactly as you want.
When you're happy with the result, you will need to approve the video in order to lock in all the edits that you've made. Approving the video is always a prerequisite to sharing your video with viewers.
You will also need to approve the video each time you make any change so that your viewers can see the updated content.
At the end of Step 5:
The status of the video is Approved to share.
Step 6: Embed and Share the Video
In this last step, you'll generate the links for the video so that each viewer can watch a customized version.
| 1. | On the Video Page, select the Share tab. |
| 2. | Make sure that the status of the video is Approved to share. |
| 3. | On the right side of the page, click the Share icon by the Embed Video option. ▶ If you have not yet created the code snippet, a plus sign (+) is displayed. |
| 4. | (Optional) If you have not yet created the code snippet, click the plus sign and create the snippet. |
| 5. | Copy and paste the embed code, placing the div element where you want the player to appear. ▶ Skip this step if you've already embedded the video. |
| 6. | Copy the POST URL and populate the request body according to the guidelines below. |
| 7. | In the code snippet, replace **Base64 response from Video API** with the SundaySky API response. |
Getting the API URL
In general, the SundaySky API uses HTTP POST requests with JSON arguments and JSON responses.
| POST URL |
|
https://apis.sundaysky.com/get-video/player-session/<SundaySky Video ID> The SundaySky Video ID can be found in the code snippet, as in the example below: |
| Request Body |
| A flat JSON object with attribute names and values. See Review the Mapping of the Data Fields to learn how to retrieve the JSON field names required for your video. We recommend including a unique identifier as the value for the id field. This will enable you to accurately report on per-user video views. For example: { "firstName": "Mitch", "department": "Finance", "id": "6tifi6h76fd4t7dj48e7tr7" } |
| Headers |
| Mandatory Content-Type: application/json Optional This enables the SundaySky platform to correctly determine the viewer's operating system, device type, and browser type. User-Agent: <user-agent value for the viewer> |
Response Codes
| Code | Message | Description |
| 200 | OK | Video generation process was successful; base64 response is returned. |
| 30X (302, 307, etc.) | Temporary redirect | Request was redirected; see response location field for the redirect URL. |
| 40X (e.g. 407) | Forbidden | The request type is malformed or not supported. |
| 501 | Not implemented | Technical exception. See response body for details. |