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://www.mycompany.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.

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: Approve 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. 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. 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.

---

Step 2: Select the URL Parameters Data Connector

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.

a.	Open the relevant video in the Studio.
b.	Select Data in the sidebar.
c.	Click Select in the data connector section.
d.	Select the URL Parameters 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:
e.	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.

---

Step 3: Review the Mapping of the Data Fields

The mapping process specifies which field in your URL corresponds to the data field in the SundaySky data library. A precise mapping ensures that the right data is pulled to populate a personalized video.
For additional guidelines, refer to the notes for Step 3 below.

a.	Open the relevant video in the Studio.
b.	Select Data in the sidebar.
c.	Click Map Fields in the data connector section.
	In the mapping window, the field of the data source (URL Parameter Key) is populated automatically according to the data field name.
d.	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.
e.	(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.

---

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

---

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.

---

Step 6: Get (Share) the Video Links

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.

Generating Video Links for a SundaySky Landing Page
Generating Video Links for a Non-SundaySky Landing Page

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

a.	On the Video Page, select the Share tab.
b.	Make sure that the status of the video is Approved to share.
c.	On the right side of the page, click the Share icon by the Landing Page option. ▶ If you have not yet created the landing page, a plus sign (+) is displayed.
d.	(Optional) If you have not yet created the landing page, click the plus sign and create the page.
e.	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.
f.	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.

---

Generating Video Links for a Non-SundaySky Landing Page

a.	On the Video Page, select the Share tab.
b.	Make sure that the status of the video is Approved to share.
c.	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.
d.	(Optional) If you have not yet created the code snippet, click the plus sign and create the snippet.
e.	Select the embed method that you want to use. ▶ By default, iframe is selected. ▶ See Embedding the SundaySky Player in a Webpage for in-depth information regarding the iframe and JavaScript embed codes.
f.	Click the Copy code icon.
g.	Paste the embed code into the HTML of your landing page, where you want the player to appear.
h.	Copy the parameters and add them to the end of the landing page URL as shown in this example: www.mycompany.com?programid=0dc1b8ad-ac04-4bd1-879f-4cd103161223&First-Name=Douglas&Plan-name=Essentials ▶ If, after defining the initial URL, you add new data fields to the video, you will need to repeat the sharing process described in this section. The parameters in this step will be updated automatically and you will need only to copy and paste them to the landing page URL.
i.	Use your distribution method (i.e. email platform) to automate the replacement of each INSERT_VALUE occurrence with the corresponding video data to create a key-value pair. This automation is what enables each viewer to see personalized content, as configured in the video.

---

Notes for Step 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');

---