Using the SundaySky API to Connect Data

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
Step 2: Select the SundaySky API Data Connector
Step 3: Map the Data Fields
Step 4: Configure the Content
Step 5: Publish the Video
Step 6: Embed and Share the Video

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:

  1. The data fields in the library are those that you require for personalization. More data fields can always be added.
  2. 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.

Data_library_name.png


Step 2: Select the SundaySky API Data Connector

bell-on.png 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.

 

Click_select.png

4.

Select the SundaySky API data connector and then click Select at the bottom of the window.

 

Select_SundaySky_API.png

 

The data connector is attached to the library and the following message is displayed:

 

SundaySky_API_selected.png

5.

Click Edit Mapped Fields to continue directly to field mapping.
▶ If you prefer mapping at a later time, click Got It! to return to the data library.

 

Edit_mapped_fields.png

At the end of Step 2:
The SundaySky API data connector is attached to the data library.

SundaySky_API_connected.png


Step 3: Map the Data Fields

bell-on.png 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.

 

Map_fields.png

 

In the mapping window, the data source field (JSON Field Name) is populated automatically according to the data field name.

 

Mapping_window.png

4.

Review each JSON field name and, if required, edit it so that it exactly matches the JSON field in your data source.
The JSON field name is case-sensitive. This means that the letter case used for the JSON field name in this mapping window must match that of the JSON key.

5.

After all the fields are mapped, click Save at the bottom of the window.

Notes for Step 3:

  • 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.

Mapping_done.png


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 message by audience. 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 viewer.

Configured_content.png

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: Publish 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 publish the video in order to lock in all the edits that you've made. Publishing is always a prerequisite to sharing your video with viewers.

You will also need to republish the video after making any changes so that your viewers can see the updated content.

To learn how to publish, see Publishing and Sharing a Video—Overview and Publishing a Video.

At the end of Step 5:
The video is published.

Video_published.png


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. Make sure that the video is published.
2. On the Video Page, click Share and then select Embed Video.
▶ If you have not yet created the code snippet, you will be prompted to do so via the Create Embed Video option.
3. (Optional) If you have not yet created the code snippet, follow steps 3-4 in Generating the Embed Code.
4. 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.
  Share_step_1.png
5. Copy the POST URL and populate the request body according to the guidelines below.
  Share_step_2.png
6. In the code snippet, replace **Base64 response from Video API** with the SundaySky API response.
  Base_64_response_snippet.png

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:
Video_ID_new.png

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.
Was this article helpful?
0 out of 0 found this helpful

Still Have Questions?

SundaySky Support is here for you

contact support