Reserved Macros and Macro Usage

info

As of 2023, Samsung states that Tizen TV's are not optimized for .NET applications. Samsung strongly recommends using JS/Web applications instead of C#/.NET applications for TVs. Please check the Lura Player Web SDK

Lura Player SDK allows parts of strings in ad tag URLs to be dynamically replaced by given or on-the-fly generated values, which in Lura Player is called macros. Macros can be a powerful tool for creating flexible and customizable ad playbacks, and can help to streamline development and improve overall user experience.

Implementing Macros

In order to add macros, you need to encapsulate your macro string by square brackets in the URLs that you've provided.

url: "https://example.com/adtag?macro1=[MACRO1]&macro2=[MACRO2]";

After specifying macros in your URLs, you can specify them using the Macros dictionary.

Macros: new Dictionary<string, string>
{
    { "MACRO1", "your_custom_macro1" },
    { "MACRO2", "your_custom_macro2" }
}

Here is an example code that uses macros in ad tag URLs:

var config = new Configuration
{
    Ads = new AdsConfiguration
    {
        Macros = new Dictionary<string, string>
        {
            { "USER_ID", "1234567890" },
            { "SESSION_ID", "078a54ef-c45e-4356-b556-a99fdab158c1" }
        },
        ClientSide = new AdsClientSideConfiguration
        {
            Provider = AdsClientSideProvider.Generic,
            Generic = new AdsGenericConfiguration
            {
                Breaks = new List<ClientsideGenericAdsInterface>
                {
                    new ClientsideGenericAdsInterface
                    {
                        Url = "https://example.com/adtag?userid=[USER_ID]&session_id=[SESSION_ID]",
                        Offset = "preroll"
                    },
                    new ClientsideGenericAdsInterface
                    {
                        Url = "https://example.com/adtag?userid=[USER_ID]&session_id=[SESSION_ID]",
                        Offset = "postroll"
                    }
                }
            }
        }
    }
};

player.SetConfig(config);

In this example code, [USER_ID] occurrences will be replaced by 1234567890 and [SESSION_ID] occurrences will be replaced by 078a54ef-c45e-4356-b556-a99fdab158c1

Reserved Macros

Some macros in Lura Player are reserved for custom functionality. Macros that start with LURA_ are reserved to be used as functional macros. Here is the list of macros that are reserved:

Attribute	Description
LURA_PAL_NONCE	Nonce generated by PAL SDK if PAL Plugin is configured and enabled
LURA_CORRELATOR	Randomly generated string

Reserved macros will be filled automatically by Lura Player, you don't need to specify them in the Macros dictionary.

caution

Note that reserved macros might increase in the future. Please note that macros that start with LURA_ prefix will be ignored.

Here is an example code that includes both custom macros and reserved macros:

var config = new Configuration
{
    Ads = new AdsConfiguration
    {
        Macros = new Dictionary<string, string>
        {
            { "MY_MACRO", "your-custom-macro" }
        },
        ClientSide = new AdsClientSideConfiguration
        {
            Provider = AdsClientSideProvider.Generic,
            Generic = new AdsGenericConfiguration
            {
                Breaks = new List<ClientsideGenericAdsInterface>
                {
                    new ClientsideGenericAdsInterface
                    {
                        Url = "https://example.com/adtag?mycustommacro=[MY_MACRO]&correlator=[LURA_CORRELATOR]&givn=[LURA_PAL_NONCE]",
                        Offset = "preroll"
                    }
                }
            }
        }
    },
    Content = new ContentConfiguration
    {
        Title = "Tears of steel",
        Media = new List<ContentMedia>
        {
            new ContentMedia
            {
                Url = "https://w3.mp.lura.live/test-assets/tears-of-steel/hls-ts.m3u8",
                Type = MediaMimeType.VideoHls
            },
            new ContentMedia
            {
                Url = "https://w3.mp.lura.live/test-assets/tears-of-steel/dash.mpd",
                Type = MediaMimeType.VideoDash
            }
        }
    }
};

player.SetConfig(config);