Using URL Parameters to Connect Data

Background

The URL Parameters connector enables you to pass data for personalization to SundaySky as key-value pairs in the page URL or with the video request via the player's endpoint URL.

Among the many ways that URL parameters can be used is within an email to landing page distribution flow. For example: you can use this connector to pass data directly from your email service platform to SundaySky.

When you send the video link to a viewer, all the URL parameters are concatenated to the landing page URL, as in the syntax example below:

https://video.YourWebsite.com/?programId=e60330cf-fbe9-4be2-b3cd-18ace9b3ba1b&First-Name=Douglas&Plan-Name=Essentials


The parameter keys added to the URL are based on the data fields used for personalizing the video. In the example below, two data fields and their respective parameter keys are displayed in the mapping window of the data library. All the parameter keys are automatically concatenated to the URL that is distributed when the video is shared. The maximum supported length of the URL is 2,000 characters.

Mapping_window_intro.jpg

The video link created for each viewer is unique and has a "sticky" ID. When you update the viewer data or the video content, the video is updated automatically. There is no need to resend viewers a new link as they can watch the updated video with the original link that they received.

In this end-to-end article, you will find comprehensive guidelines for working with URL parameters, beginning with setting up a data library and concluding with generating video links for your viewers.


Step 1: Select or Create a Data Library
Step 2: Select the URL Parameters Data Connector
Step 3: Review the Mapping of the Data Fields
Step 4: Configure the Content
Step 5: Publish the Video
Step 6: Get (Share) the Video Links

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 that you want. SundaySky supports three methods of personalization: using a personalization token, audience messaging, and show/skip scene.

  • When using a personalization token, you only need to add data fields to the data library before you can use them.
  • For audience messaging 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. You may require additional data fields that currently do not exist in the library. These can be added freely without negatively impacting any existing videos.
  2. The data library is connected to the URL Parameters data connector.

If you find a data library that has the data fields that you need but the library's data connector is not URL Parameters, do not change the library's data connector as this will negatively impact existing videos that are connected to the library. 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.jpg


Step 2: Select the URL Parameters Data Connector

bell-on.png If you selected a data library that is already connected to the URL Parameters 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 in your company. Put simply, the connector is what determines how data flows from your company to SundaySky.

1.

Open the relevant video in the Studio.

2.

Select Data in the sidebar.

3.

Click Select in the data connector section.

 

Click_select.jpg

4.

Select the URL Parameters data connector and then click Select at the bottom of the window.

 

Select_URL_Parameters_120.jpg

 

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

 

URL_parameters_selected.jpg

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

At the end of Step 2:
The URL Parameters data connector is attached to the data library.

URL_parameters_connector_selected.jpg


Step 3: Review the Mapping of 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 field in your company records corresponds to the data field in the SundaySky data library. A precise mapping ensures that the right data is pulled from your records 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.jpg

 

In the mapping window, the field of the data source (URL Parameter Key) is populated automatically according to the data field name.

 

Review_mapped_fields.jpg

4.

Review each pair and make sure that the relevant URL parameter key (in your data source) is mapped to each data field in the data library. If the URL parameter key is incorrect, edit it accordingly.
As any edit will affect every video using this data library, we recommend making edits cautiously.

5.

(Optional) If you make any changes while reviewing the field mapping, click Save at the bottom of the window.


Notes for Step 3:

  • If you rename a data field after the mapping process, the URL Parameter Key field 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 always review its mapping.

At the end of Step 3:
Each URL parameter key (data source field) is mapped correctly to the data field.

Step_3_completed.jpg


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.

Personalization_example.jpg

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
Text: Message by Audience

Configuring a Voice-over with a Personalization Token
Voice-over: Message by Audience

Configuring Media According to a Data Stream
Media: Message by 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.

Published_status.jpg


In this last step, you're ready to generate the links for the video so that each viewer can watch a customized version. The actions in this step depend on whether you are using the SundaySky landing page or your own page to play the video.

As mentioned previously, each video link is generated with a "sticky" ID, unique to each viewer. Because of this, it is not necessary to resend links after you update the video content or update the viewer data. After any update, viewers only need to revisit the original link they received in order to see the updated content.

Generating Video Links for a SundaySky Landing Page

1. Make sure that the video is published.
2. On the Video Page, click Share and then select SundaySky Landing Page.
▶ If you have not yet created a landing page, the option name is Create SundaySky Landing Page. You will need to create a landing page before continuing.
3.

Copy and paste the landing page URL into your distribution platform.
▶ Note that the parameter keys that you defined are concatenated to the URL. In the example below, First-Name and Plan-Name are concatenated as they are the fields that are being used for personalization.

  Ssky_landing_page_step_1.jpg
4. In the video link sent to your viewers, replace each INSERT_VALUE occurrence with the corresponding video data to create a key-value pair, as in this example.
  Ssky_landing_page_step_2.jpg

Generating Video Links for a Non-SundaySky Landing Page

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, the option name is Create Embed Video.
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 into your website editor.
▶ Skip this step if the code is already embedded.
  Embed_code_step_1.jpg
5. Replace each INSERT_VALUE occurrence with the corresponding video data to create a key-value pair, as in this example.
  Embed_code_step_2.jpg
6. Depending on whether you want the URL parameters to be visible or not, use either of the following methods:
  a. Pass the URL parameters through the landing page URL
  When using this option, the URL parameters are visible to the viewer.
Embed the SundaySky player code in your page and then distribute the URL string with the concatenated parameters.
  b. Pass the URL parameters directly to the SundaySky player
  When using this option, the URL parameters are not visible to the viewer.
Embed the SundaySky player code in your page and then inject the parameters directly into the SundaySky player attribute "endpoint-URL" as in the example below:

sskyplayer.setAttribute('endpoint-url', 'https://apis.sundaysky.com/get-video/player-session/'+sskyProgramId+'?id=123456&First-Name=Douglas&Plan-Name=Essentials');

At the end of Step 6:
The personalized video links are generated, ready to be distributed by the method you prefer.

Was this article helpful?
0 out of 0 found this helpful

Still Have Questions?

SundaySky Support is here for you

contact support