Below you can find the list of available macros and their definitions used within the Telos SSAI.
These macros can be implemented in ad tags to dynamically pass specific data.
| Name | Tag Macros | Category | Description | Example Usage | Allowed Values | Constraints |
| Master playlist source URL | {m} | Stitcher | The base64 encoded HLS master playlist URL. This URL points to the video source that will be used as the primary stream. | m=aHR0cDovL2hscy10cmFuc2NvZGVyLnR2c3RpdGNoLmNvbS9uby1zbGF0ZS9tYXN0ZXIubTN1OA== | Base64 encoded URL string | Required. Must be a valid base64 encoded URL (see detailed steps for how to encode below). |
| User ID | {u} | Stitcher | A unique identifier for the user accessing the stream. Used to track individual user sessions and personalize content delivery. | u=testuser | String (e.g., alphanumeric user ID) | Required. Must be unique per user session. |
| Ad triggers included in playlist source | {isNoSlate} | Stitcher | This flag controls whether ads are inserted as additional content without replacing the main content. When enabled, ads appear alongside the main video. Use this if your HLS playlist does not include cue points. | isNoSlate=true | Boolean (true, false, 1, 0) | Optional. Default is false. Must be consistent with the content playout strategy. |
| Ad insertion interval | {adInterval} | Stitcher | Specifies the time interval in seconds between consecutive ad insertions. Only works when no slate mode is enabled. | adInterval=600 | Integer (seconds) | Optional. Only required if isNoSlate=1 (true). |
| Ad pod duration | {adDuration} | Stitcher | Defines the maximum duration of each ad break (block) in seconds. This controls how long each ad segment will play before returning to the main content. | adDuration=60 | Integer (seconds) | Required if ads are being inserted. |
| Pre-roll ad block | {preroll} | Stitcher | Enables or disables pre-roll ads that play before the main content begins. Useful for ensuring an ad plays as soon as a user connects to the stream. | preroll=1 | Boolean (true, false, 1, 0) | Optional. Default is false. |
| Pre-roll offset | {prerollOffset} | Stitcher | Specifies the duration in seconds before preroll ads. Result depends on HLS segments duration. | prerollOffset=5 | Integer (seconds) | Optional. Default value is 8 seconds. |
| Cue Point | {cuePoint} | Stitcher | Indicates whether to use only SCTE cues that were provided in HLS stream | cuePoint=1 | Boolean (true, 1, TRUE) or not | Optional. Default value is false. |
| Format | {format} | Stitcher | Parameter which can be used to override default format for specific OTT encoding ladder, such as bitrate, codecs, etc | format=ott-studio-p31 | Integer or String (e.g., numeric or alphanumeric identifier) | Optional |
| Aid | {aid} | CTV | Identifies the source ID within the stitching system. This helps in tracking and reporting on the ad delivery across various channels or platforms. | aid=478241 | Integer or String (e.g., numeric or alphanumeric identifier) | Required. Used for reporting and analytics. Must match predefined IDs in the system. |
| Site full URL | {site_full_url} | CTV | The full URL of the site where the video content is being streamed. This is used to track the source of the request and for analytical purposes. | site_full_url=test.com | String (valid URL format) | Optional. Must be a valid and fully qualified URL. |
| Device User Agent | {ua} | CTV | The User-Agent string from the device accessing the content. This string identifies the browser and device, enabling optimized content delivery. | ua=Mozilla/5.0 (Linux; Android 2.2; Mobile; Safari/533.1) | String (User-Agent format) | Optional. Useful for analytics and content adaptation. |
| IP Address | {uip} | CTV | The IP address of the device making the request. Used for geolocation, content personalization, and analytics. | uip=192.168.1.1 | IPv4 or IPv6 address | Optional. Sensitive information, please handle with care. |
| App name | {app_name} | CTV | The name of the application making the request. Helps in identifying and tracking the app usage for better targeting and reporting. | app_name=ExampleApp | String | Optional. Should match the name registered in app stores or internal tracking systems. |
| App bundle | {app_bundle} | CTV | The unique bundle identifier for the application. This identifier is used to track app-specific data, especially in mobile environments. | app_bundle=com.example.app | String (e.g., reverse DNS format) | Optional. Important for mobile app tracking. |
| Device Model | {device_model} | CTV | The model of the device accessing the stream, such as the specific smartphone or smart TV model. This helps in content optimization and analytics. | device_model=iPhone10,6 | String | Optional. Provides insight into the types of devices accessing the content. |
| Device Manufacturer | {device_make} | CTV | The manufacturer of the device, such as Apple, Samsung, etc. Used for analytics and potentially for optimizing content based on device capabilities. | device_make=Apple | String | Optional. Useful for brand-specific analytics and content adaptation. |
| Device Category | {device_category} | CTV | Indicates the category of the device, such as smartphone, tablet, PC, smart TV, etc. This categorization helps in tailoring the content experience to the device type. | device_category=4 | Integer (e.g., 1=PC, 2=Smartphone3=Tablet, 4=Smart TV, 5=Set-Top Box) | Optional. Enhances targeting and content delivery. |
| App store URL | {app_store_url} | CTV | The URL of the application in the app store. Used for cross-promotion, app installation campaigns, and tracking user acquisition sources. | app_store_url=https://itunes.apple.com/app/example | String (valid URL format) | Optional. Useful for app promotion and user acquisition analytics. |
| Device ID | {device_id} | CTV | A unique identifier for the device accessing the content. This can be used for tracking, personalization, and delivering a consistent user experience across sessions. | device_id=abcd1234 | String (unique identifier format) | Optional. Important for maintaining user continuity and personalized experiences. |