tencent cloud

SSAI Click-through
Download PDF
Last updated:2026-01-28 17:35:20
SSAI Click-through
Last updated: 2026-01-28 17:35:20
Download PDF

Overview

StreamPackage now supports the SSAI click-through feature, allowing users to click ads and navigate to the advertiser's designated webpage while recording click data. The feature has the following advantages:
Complete click experience: supports ad display, click, redirection, and tracking.
Real-time data synchronization: the latest click-through information can be obtained through periodic polling.

Overall Architecture and Workflow


Process description
1. Session initialization: The player requests the Session API to get manifestUrl and trackingUrl.
2. Start playback: Use manifestUrl to start playing the video and refresh the playlist at targetDuration frequency.
3. Tracking poll: Poll trackingUrl at the same targetDuration frequency to get ad click info.
4. Process data: Parse the returned clickThrough event and register a click listener for the ad.
5. User interaction: When a user clicks the ad, navigate to the landing page in beaconUrls.
Key point
The player's playlist update and tracking poll should use the same time interval (targetDuration).
The tracking API implements incremental data updates. Events that have been returned will not be resent.
Tracking information is only returned for ads that are actually inserted into the stream.

Quick Start

1. Retrieve session information

When the player is initialized, request the session initialization API. 
POST /v1/ssai/session/{ChannelId}/xxx.m3u8
Response example:
{
    "manifestUrl": "/v1/ssai/master/{ChannelId}/main.m3u8?session_id={SessionId}",
    "trackingUrl": "/v1/ssai/tracking/{ChannelId}/{SessionId}"
}
Description:
manifestUrl: the playlist URL used for video playback.
trackingUrl: the tracking information URL used to obtain click data.
{SessionId}: the unique ID of the session.

2. Start playing

Use the returned manifestUrl to start playing.
// Initialize the player
player.setSrc(manifestUrl);
player.play();

3. Periodic polling of tracking information

The player should periodically request the tracking API (trackingUrl) to obtain ad click data. It is recommended that the polling interval matches the targetDuration of the HLS playlist, similar to how the player regularly requests manifestUrl to update the playlist.
GET /v1/ssai/tracking/{ChannelId}/{SessionId}
Response example:
{
  "avails": [
    {
      "ads": [
        {
          "adId": "ad_001",
          "duration": "PT30.0S",
          "durationInSeconds": 30,
          "startTime": "PT0.0S",
          "startTimeInSeconds": 0,
          "adSystem": "Advertisement system name",
          "title": "Product Promotion"
          "adServerId": "ad_server_001",
          "trackingEvents": [
            {
              "eventType": "clickThrough",
              "beaconUrls": [
                "https://advertiser.com/landing-page"
              ],
              "startTimeInSeconds": 0
            }
          ]
        }
      ],
      "startTime": "PT0.0S",
      "startTimeInSeconds": 0
    }
  ]
}

Request and Response Description

1. Session initialization API

Response field:
Field
Type
Description
manifestUrl
string
Playback list URL.
trackingUrl
string
Tracking information URL.

2. Tracking information API

Request Parameters:
Parameter
Type
Description
ConfigId
string
SSAI Configuration ID.
SessionToken
string
Session token.
Response field:
Field
Type
Description
avails
array
Ad Space array.
avails array content:
Field
Type
Description
ads
array
Ad array.
startTime
string
Ad Space start time (ISO 8601 format, such as "PT0.0S").
startTimeInSeconds
number
Ad Space start time (seconds).
ads array content:
Field
Type
Description
adId
string
Ad ID (Creative ID).
duration
string
Ad duration (ISO 8601 format, such as "PT30.0S").
durationInSeconds
number
Ad duration (seconds).
startTime
string
Ad start time (ISO 8601 format).
startTimeInSeconds
number
Ad start time (seconds).
adSystem
string
Advertisement system name.
title
string
Ad title.
adServerId
string
Ad server ID.
trackingEvents
array
Tracking event array.
trackingEvents array content:
Field
Type
Description
eventType
string
Event type (currently returns clickThrough only).
beaconUrls
array
Click-through URL list.
startTimeInSeconds
number
Event trigger time (seconds).

Event Type Description

ClickThrough
Trigger timing: user click ad.
Purpose: redirect to the advertiser's destination page (landing page).
Processing method: direct jump to the URL in beaconUrls.
Field description:
eventType: "clickThrough".
beaconUrls: list of destination URLs for click redirect (usually only one URL).
startTimeInSeconds: event trigger time point.
Note:
The Tracking API only returns clickThrough events for ad click redirect.
impression, clickTracking and other events are automatically processed by the server.
clickThrough information is only returned for ads that are actually inserted into the stream.

FAQs

How many should the polling interval be set?

It is recommended to remain consistent with the targetDuration of the HLS playlist (typically 6-10 seconds). Just as the player periodically requests the manifest URL for playlist updates, the polling of the tracking API should follow the same pace. In this way:
Timely acquisition of latest ad click info.
Avoid causing excessive pressure on the server.
Maintain consistency with video playback logic.

Is click data updated in real time?

Yes. The tracking API uses poll mode, and the latest unsent ad click info will be returned for each request. Returned events will not be resent.

What to do if there is no click info for the ad?

When the tracking API returns an empty avails array, it means there are currently no new click info. This is likely because:
The VAST response contains no ClickThrough data for the ad.
All click info was returned in previous poll.
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback