Reserved Macros and Macro Usage

LuraPlayer SDK allows parts of strings in ad tag URLs to be dynamically replaced by given or on the fly generated values, which in LuraPlayer is called as 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 the macros, in your URLs, you can specify them using macros attribute.

macros: {
    MACRO1: "your_custom_macro1",
    MACRO2: "your_custom_macro2",
}

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

const config = {
  ...
  ads: {
    macros: {
      USER_ID: "1234567890",
      SESSION_ID: "078a54ef-c45e-4356-b556-a99fdab158c1",
    },
    clientSide: {
      provider: "generic",
      generic: {
        breaks: [
          {
            url: "https://example.com/adtag?userid=[USER_ID]&session_id=[SESSION_ID]",
            offset: "preroll",
          },
          {
            url: "https://example.com/adtag?userid=[USER_ID]&session_id=[SESSION_ID]",
            offset: "postroll",
          },
        ],
      },
    },
  },
  ...
};
const player = new lura.Player(document.getElementById("player"));
player.setConfig(config);

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

Reserved Macros

Some macros in LuraPlayer are reserved for custom functionality. Macros that starts with LURA_ are reserved to be used as functional macros. Here are the list of the 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 LuraPlayer, you don't need to specify them in the macros attribute.

caution

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

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

const config = {
  ads: {
    macros: {
      MY_MACRO: "your-custom-macro",
    },
    clientSide: {
      provider: "generic",
      generic: {
        breaks: [
          {
            url: "https://example.com/adtag?mycustommacro=[MY_MACRO]&correlator=[LURA_CORRELATOR]&givn=[LURA_PAL_NONCE]",
            offset: "preroll",
          },
        ],
      },
    },
  },
  content: {
    title: "Tears of steel",
    media: [
      {
        url: "https://w3.mp.lura.live/test-assets/tears-of-steel/hls-ts.m3u8",
        type: "application/x-mpegURL",
      },
      {
        url: "https://w3.mp.lura.live/test-assets/tears-of-steel/dash.mpd",
        type: "application/dash+xml",
      },
    ],
  },
  plugins: {
    pal: {
      enabled: true,
      allowStorageConsent: true,
      ppid: "12DJD92J02KXVLS9D817DCJ078S8F1J2",
      descriptionUrl: "https://docs4.lura.app/",
    },
  },
};
const player = new lura.Player(document.getElementById("player"));
player.setConfig(config);