tencent cloud

Server-Side Ad Insertion
Download PDF
Last updated: 2025-12-12 17:44:41
Server-Side Ad Insertion
Last updated: 2025-12-12 17:44:41
Download PDF

AD insertion

With the advancement of streaming media technology and applications on internet, it is apparent that ad-supported streaming media delivery has become a major monetization strategy. By using Tencent Cloud's Stream Service, you can implement dynamic ad insertion based on SCTE-35 ad markers and SSAI. The complete general process of SSAI is as follows:

Transmit content sources with ad markers to StreamPackage. For example, in the case of a live content source, you can push the live stream to StreamLive for transcoding and insertion of ad SCTE-35 markers, and then transmit it to StreamPackage. If there are no subsequent processes, all server-side steps for CSAI have been completed. And subsequent process for SSAI is as follows:
1. The player requests the manifest (m3u8/mpd), and StreamPackage fetches the origin manifest while parsing the manifest and checking the SCTE-35 ad markers.
2. StreamPackage send the request to the Ad Decision Server, parses the VAST/VMAP response, and obtains the ad video address.
3. StreamPackage downloads the ad video, transcodes and stores it.
4. StreamPackage updates the transcoded ad segment url in the manifest by inserting and replacing, and then distribute it.
5. After the ad is played on the client-side, StreamPackage reports to the ad tracking service for tracking the event.
If you use this AD insertion feature. AD insertion fee will be incurred.

Step 1: Create ad insertion configuration




In the StreamPackage console, click Create Configuration to enter the configuration page, which includes the following configurations:
Required settings: Essential configuration information, including Configuration Name, Content Source and Ad Decision Server.
Configuration aliases：Configuration aliases are used for dynamic parameter replacement.
Personalization details：Optional settings for ad break personalization.
Advanced settings：Advanced settings allow you to fine-tune properties related to your content delivery network (CDN) prefix, DASH.

Step 2: Fill in the required settings




Name
The Configuration Name is a unique identifier for an ad insertion configuration. It can include numbers, letters, underscores (_), hyphens (-), and supports up to 512 characters.
Content Source
Enter the URL prefix of the source stream. For example, entering http://origin-server.com/abc/ as the URL prefix can apply to all source streams with the same prefix, such as http://origin-server.com/abc/example_1.m3u8, http://origin-server.com/abc/example_2.m3u8, etc. It supports up to 25,000 characters.
Ad decision server
The ad decision server (ADS) is the origin server that’s providing content to StreamPackage. It determines which ads StreamPackage will insert in ad breaks in the manifest. Please enter an address starting with http:// or https://, supporting up to 25,000 characters.

Step 3: Configure aliases

Player parameters and aliases used for dynamic variable replacement. Click Add player parameter, Edit, Delete on the right to maintain player parameters. Parameter name can contain up to 32 letters, digits, underscores(_), and dashes(-).



Enter alias key name and alias value in the parameter. You'll use the alias key as a player parameter variable during dynamic variable replacement. StreamPackage will replace the alias key with the mapped alias value.

An example

1. URL for the ADS.
https://my.ads.com/path?ad_type=[player_params.ad_type]&region=[player_params.region]
2. Aliases for dynamic variable replacement.
"ConfigurationAliases": {
    "player_params.ad_type": {
        "customized": "abc",
        "default": "default"
    },
    "player_params.region": {
        "india": "ap-mumbai",
        "japan": "ap-tokyo"
    },
}
3. Add key-value in the request to StreamPackage.
<master>.m3u8?ad_type=customized&region=india
4. StreamPackage will pass the parameters to ADS.
https://my.ads.com/path?ad_type=abc&region=ap-mumbai

Step4: Set default slate ad

The slate ad is a default ad that’s used if an ad break isn’t filled by an ad replacement. It lets you define what happens when an ad break isn’t completely filled by the ads dictated by the ad decision server (ADS). This way, if an ad is unavailable or too short, or if network conditions prevent the ad decision server from responding to StreamPackage, you know exactly what will be played instead. If an ad slate isn’t specified, then the default is to show the underlying content stream. The URL for the slate ad is an address starting with http:// or https://. Maximum 25,000 characters.

The personalization threshold sets the maximum duration (in seconds) of underfilled ad time allowed in an ad break. If the duration of underfilled ad time exceeds the personalization threshold, then personalization of the ad break is abandoned and the underlying content is shown.

Step 5: Configure pre - roll ad

StreamPackage supports inserting pre-roll ads at the beginning of a live stream, before the main content starts. The ad decision server determines which ads StreamPackage will insert.

Live pre-roll ad decision server
The live pre-roll ad decision server is the origin server that’s providing pre-roll ad content to StreamPackage. It determines which ads StreamPackage will insert at the beginning of the live stream. Please enter an address starting with http:// or https://, supporting up to 25,000 characters.
Live pre-roll maximum allowed duration
The pre-roll maximum duration sets a limit on how much time ads can take before the main content starts. If the ADS returns more ads than will fit in the maximum duration, StreamPackage fills as much of the avail as possible without going over.

Step 6: Advanced settings




CDN content segment prefix: The CDN prefix for the source stream segments.
Ad marker passthrough: Enable or disable the ad marker passthrough.
SCTE-35 ad message type: Configure which tags in the input video stream are treated as ad markers.

Step 7: Generate playback URL with inserted ad




The full URL of the source stream:
http://origin-server.com/abc/main.m3u8
The prefix entered at the content source:
http://origin-server.com/abc/
Generated playback endpoint prefix:
http://xxx.streampackage.srclivepull.myqcloud.com/v1/ssai/master/<uniq_id>/
Complete advertising replacement playback URL:
http://xxx.streampackage.srclivepull.myqcloud.com/v1/ssai/master/<uniq_id>/main.m3u8

Step 8: Origin manifest and personalized manifest after replacement

The following examples provide a comparison between the origin manifest and the personalized manifest after replacement.

Origin manifest

Here is an example of the HLS master manifest obtained by StreamPackage from the original stream: 
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-INDEPENDENT-SEGMENTS
#EXT-X-STREAM-INF:PROGRAM-ID=0,BANDWIDTH=500000,RESOLUTION=640x360
tx_ssai_temp1.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=0,BANDWIDTH=2000000,RESOLUTION=960x540
tx_ssai_temp2.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=0,BANDWIDTH=3000000,RESOLUTION=1280x720
tx_ssai_temp3.m3u8
Here is an example of the HLS media manifest obtained by StreamPackage from the original stream, which includes inserted SCTE-35 markers:
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-MEDIA-SEQUENCE:11035046
#EXT-X-TARGETDURATION:4
#EXTINF:4.000, no desc seq 11035047
6594D5C2000003872642-p0_tmplav1_av1-1712914648040.ts?pts=118443600&txl=1712914652444&enter_ts=1712914655931&11035047
#EXTINF:0.133, no desc seq 11035048
6594D5C2000003872642-p0_tmplav1_av1-1712914652040.ts?pts=118803600&txl=1712914655932&enter_ts=1712914656383&11035048
#EXT-OATCLS-SCTE35:/AAgAAAAAAAAAAAADwUAAAABAPCAABSZcAAAAAAAABcABfA=
#EXT-X-CUE-OUT:15
#EXTINF:4.000, no desc seq 11035049
6594D5C2000003872642-p0_tmplav1_av1-1712914652173.ts?pts=118815570&txl=1712914656383&enter_ts=1712914660810&11035049
#EXT-X-CUE-OUT-CONT:ElapsedTime=4,Duration=15,SCTE35=/AAgAAAAAAAAAAAADwUAAAABAPCAABSZcAAAAAAAABcABfA=
#EXTINF:4.000, no desc seq 11035050
6594D5C2000003872642-p0_tmplav1_av1-1712914656173.ts?pts=119175570&txl=1712914660812&enter_ts=1712914664291&11035050
#EXT-X-CUE-OUT-CONT:ElapsedTime=8,Duration=15,SCTE35=/AAgAAAAAAAAAAAADwUAAAABAPCAABSZcAAAAAAAABcABfA=
#EXTINF:4.000, no desc seq 11035051
6594D5C2000003872642-p0_tmplav1_av1-1712914660173.ts?pts=119535570&txl=1712914664294&enter_ts=1712914668214&11035051
#EXT-X-CUE-OUT-CONT:ElapsedTime=12,Duration=15,SCTE35=/AAgAAAAAAAAAAAADwUAAAABAPCAABSZcAAAAAAAABcABfA=
#EXTINF:3.000, no desc seq 11035052
6594D5C2000003872642-p0_tmplav1_av1-1712914664173.ts?pts=119895570&txl=1712914668214&enter_ts=1712914671229&11035052
#EXT-X-CUE-IN
#EXTINF:0.834, no desc seq 11035053
6594D5C2000003872642-p0_tmplav1_av1-1712914667173.ts?pts=120165570&txl=1712914671231&enter_ts=1712914672750&11035053

Personalized manifest

Here is an example of the personalized HLS master manifest generated by StreamPackage:
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-INDEPENDENT-SEGMENTS
#EXT-X-STREAM-INF:PROGRAM-ID=0,BANDWIDTH=500000,RESOLUTION=640x360
../../manifest/018ec77ac9b309dc0f327e4b2d86/31bfddb8b8b73de51338eb764b3621c0/tx_ssai_temp1.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=0,BANDWIDTH=2000000,RESOLUTION=960x540
../../manifest/018ec77ac9b309dc0f327e4b2d86/31bfddb8b8b73de51338eb764b3621c0/tx_ssai_temp2.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=0,BANDWIDTH=3000000,RESOLUTION=1280x720
../../manifest/018ec77ac9b309dc0f327e4b2d86/31bfddb8b8b73de51338eb764b3621c0/tx_ssai_temp3.m3u8
Here is an example of the personalized HLS media manifest generated by StreamPackage:
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-MEDIA-SEQUENCE:11035046
#EXT-X-TARGETDURATION:4
#EXTINF:4.000, no desc seq 11035047
http://251009588.ap-mumbai.streampackage.srclivepull.myqcloud.com/v1/018c8bc8788509dc0f3266bdec93/018ed19540a809dc0f327a192df3/6594D5C2000003872642-p0_tmplav1_av1-1712914648040.ts?pts=118443600&txl=1712914652444&enter_ts=1712914655931&11035047
#EXTINF:0.133, no desc seq 11035048
http://251009588.ap-mumbai.streampackage.srclivepull.myqcloud.com/v1/018c8bc8788509dc0f3266bdec93/018ed19540a809dc0f327a192df3/6594D5C2000003872642-p0_tmplav1_av1-1712914652040.ts?pts=118803600&txl=1712914655932&enter_ts=1712914656383&11035048
#EXT-OATCLS-SCTE35:/AAgAAAAAAAAAAAADwUAAAABAPCAABSZcAAAAAAAABcABfA=
#EXT-X-CUE-OUT:15
#EXT-X-DISCONTINUITY
#EXTINF:2.000,
../../segment/018ec77ac9b309dc0f327e4b2d86/6bb76e30ee193e2a08c3fbf5c5356eac/dGVzdF9hdjEubTN1OA==/11035048_1.ts
#EXTINF:2.000,
../../segment/018ec77ac9b309dc0f327e4b2d86/6bb76e30ee193e2a08c3fbf5c5356eac/dGVzdF9hdjEubTN1OA==/11035049_1.ts
#EXTINF:2.000,
../../segment/018ec77ac9b309dc0f327e4b2d86/6bb76e30ee193e2a08c3fbf5c5356eac/dGVzdF9hdjEubTN1OA==/11035050_1.ts
#EXTINF:2.000,
../../segment/018ec77ac9b309dc0f327e4b2d86/6bb76e30ee193e2a08c3fbf5c5356eac/dGVzdF9hdjEubTN1OA==/11035051_1.ts
#EXTINF:2.000,
../../segment/018ec77ac9b309dc0f327e4b2d86/6bb76e30ee193e2a08c3fbf5c5356eac/dGVzdF9hdjEubTN1OA==/11035052_1.ts
#EXTINF:2.000,
../../segment/018ec77ac9b309dc0f327e4b2d86/6bb76e30ee193e2a08c3fbf5c5356eac/dGVzdF9hdjEubTN1OA==/11035053_1.ts
#EXTINF:2.000,
../../segment/018ec77ac9b309dc0f327e4b2d86/6bb76e30ee193e2a08c3fbf5c5356eac/dGVzdF9hdjEubTN1OA==/11035054_1.ts
#EXTINF:1.000,
../../segment/018ec77ac9b309dc0f327e4b2d86/6bb76e30ee193e2a08c3fbf5c5356eac/dGVzdF9hdjEubTN1OA==/11035055_1.ts
#EXT-X-CUE-IN
#EXT-X-DISCONTINUITY
#EXTINF:0.834, no desc seq 11035053
http://251009588.ap-mumbai.streampackage.srclivepull.myqcloud.com/v1/018c8bc8788509dc0f3266bdec93/018ed19540a809dc0f327a192

Step 9: View advertising insertion statistical data

Once the business is started, you can view relevant statistical data:
In the page header, aggregated data can be viewed.
In the table, detailed data can be viewed and downloaded.

Metric Name
Description
Channel Name
Ad insertion configuration name, consistent with the name in the Ad Insertion Configurations page.
Channel ID
Ad insertion configuration ID, consistent with the ID in the Ad Insertion Configurations page.
Ad Type
Ad type: Pre-roll, Mid-roll.
Successful Ad Request
Number of successful ad requests: the number of times the ad server successfully returns advertising content.
Failed Ad Request
Number of failed ad requests: the number of times the ad server fails to return or the returned content does not contain advertising content.
Impression
Number of impressions: the number of times ads are successfully played on the client side.
Start
Play count at start: the total number of times all advertising content has been played at the starting position.
First Quartile
Play count at 1/4 quantile: the total number of times all advertising content has been played to the 1/4 position.
Midpoint
Play count at 1/2 quantile: The total number of times all advertising content has been played to the 1/2 position.
Third Quartile
Play count at 3/4 quantile: The total number of times all advertising content has been played to the 3/4 position.
Complete
Play count at completion: The total number of times all advertising content has been played to completion.
Mid-roll Ad Personalization Fill Rate
Total duration of mid-roll ad replacement / Total duration of ad tags.
Pre-roll Ad Replacement Success Rate
Successful count of pre-roll ad replacement / Total number of requests.
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback