Create an ad optimization experience

Ad optimization allows you to tailor server-side ad experiences for different audiences. Create audience segments from request and media data, then define the advertising behavior that JWX applies when each segment matches.

Prerequisites

Create an ad optimization experience

Follow these steps to create an ad optimization experience:

1. On the Ad insertion page, under the Ad optimization tab, click Create ad optimization. The ad optimization details page appears.

2. Enter a Name for the experience.

3. Set up advertising.

   💡

   You can also use the JSON editor to define the ad optimization experience (steps 3–5).

4. Configure bumpers and stitch mode.

5. Configure advanced settings.

6. Click Save. The ad optimization experience appears on the Ad optimization tab, along with its ID.

7. In the row of the ad optimization, in the ID column, click (copy icon) to copy the ID to your clipboard.

8. In your SSAI manifest request, add the ID as the value for ad_config_id. This activates the ad optimization experience.

   Text

   https://cdn.jwplayer.com/v2/sites/{site_id}/media/{media_id}/ssai.{manifest_extension}?ad_config_id={ad_optimization_id}

The ad optimization experience is now applied to the viewer session. JWX evaluates the request against the configured audience segments and returns the resulting SSAI manifest.

Set up advertising

Follow these steps to set up advertising:

1. On the Advertising tab, click + Add default. The Add default audience segment panel appears.

2. Enter a Name for the default segment.

3. From the dropdown menu, select an Ad config to apply when no advertising audience segment matches.

4. (Optional) Click Split traffic to distribute the default traffic across multiple ad configs:

   1. Select ad config A and enter its traffic percentage.

   2. Select ad config B and enter its traffic percentage.

   3. (Optional) Click + Add ad config to add additional ad configs.

      💡

      Click Split evenly to adjust all traffic to an equal percentage across the ad configs.

5. Click Save. The default segment appears under Advertising.

6. Click + Create audience segment. The Create audience segment panel appears.

7. Enter a Name for the segment.

8. Under If all of the following is true, define the condition:

   1. From Select parameter, choose the source of the value. Values include Query, Media, Date & time, Location, Device type, Platform, Browser, and Referrer.

   2. Set the parameter value.

      Parameter	Steps
      Query	Follow these steps: Enter the key to evaluate. Select a comparison operator. Enter or select the comparison value.
      Media	Follow these steps: Enter the key to evaluate. Select a comparison operator. Enter or select the comparison value.
      Date & time	Follow these steps: Select a comparison operator. Select a date from the calendar dropdown menu. Select a time from the clock dropdown menu.
      Location	Follow these steps: Select a comparison operator. Select a country to target from the dropdown menu.
      Device type	Follow these steps: Select a comparison operator. Select a device type to target from the dropdown menu.
      Platform	Follow these steps: Select a comparison operator. Select a platform to target from the dropdown menu.
      Browser	Follow these steps: Select a comparison operator. Select a browser to target from the dropdown menu.
      Referrer	Follow these steps: Select a comparison operator. Enter the request source URL to target in the text box.

   3. (Optional) Click + Add condition and repeat steps 8a–b.

9. Under Then, select the Ad config to apply to matching requests.

10. (Optional) Click Split traffic to distribute matching traffic across multiple ad configs. Follow the guidance in steps 4a–c.

11. Click Save. The segment appears under Advertising.

12. (Optional) Repeat steps 6–11 to create additional audience segments.

13. If multiple segments exist, drag the segments into the order JWX should evaluate them. JWX prioritizes segments from top to bottom.

↳ Return to main step 4.

Configure bumpers and stitch mode

Define the bumper or stitching behavior without changing the ad config assigned to the same request.

Bumpers

Follow these steps to configure bumpers:

1. On the Bumpers and stitch mode tab, in the Bumpers section, click + Create audience segment. The Create audience segment panel appears.
2. Enter a Name for the segment.
3. Under If all of the following is true, define the condition:

   1. From Select parameter, choose the source of the value.

   2. Set the parameter value.

      Parameter	Steps
      Query	Follow these steps: Enter the key to evaluate. Select a comparison operator. Enter or select the comparison value.
      Media	Follow these steps: Enter the key to evaluate. Select a comparison operator. Enter or select the comparison value.
      Date & time	Follow these steps: Select a comparison operator. Select a date from the calendar dropdown menu. Select a time from the clock dropdown menu.
      Location	Follow these steps: Select a comparison operator. Select a country to target from the dropdown menu.
      Device type	Follow these steps: Select a comparison operator. Select a device type to target from the dropdown menu.
      Platform	Follow these steps: Select a comparison operator. Select a platform to target from the dropdown menu.
      Browser	Follow these steps: Select a comparison operator. Select a browser to target from the dropdown menu.
      Referrer	Follow these steps: Select a comparison operator. Enter the request source URL to target in the text box.

   3. (Optional) Click + Add condition and repeat steps 3a–b. All conditions must be true for the segment to match.

4. Under Then, set Bumpers to ON to enable bumpers for matching requests. Keep the default OFF setting to disable them.
5. Click Save. The segment appears under Bumpers.
6. (Optional) Repeat steps 1–5 to create additional audience segments for bumpers.
7. If multiple segments exist, drag the segments into the order JWX should evaluate them. JWX prioritizes segments from top to bottom.

Stitch mode

Follow these steps to configure stitch mode:

1. On the Bumpers and stitch mode tab, in the Stitch mode section, click + Create audience segment. The Create audience segment panel appears.

2. Enter a Name for the segment.

3. Under If all of the following is true, define the condition:

   1. From Select parameter, choose the source of the value.

   2. Set the parameter value.

      Parameter	Steps
      Query	Follow these steps: Enter the key to evaluate. Select a comparison operator. Enter or select the comparison value.
      Media	Follow these steps: Enter the key to evaluate. Select a comparison operator. Enter or select the comparison value.
      Date & time	Follow these steps: Select a comparison operator. Select a date from the calendar dropdown menu. Select a time from the clock dropdown menu.
      Location	Follow these steps: Select a comparison operator. Select a country to target from the dropdown menu.
      Device type	Follow these steps: Select a comparison operator. Select a device type to target from the dropdown menu.
      Platform	Follow these steps: Select a comparison operator. Select a platform to target from the dropdown menu.
      Browser	Follow these steps: Select a comparison operator. Select a browser to target from the dropdown menu.
      Referrer	Follow these steps: Select a comparison operator. Enter the request source URL to target in the text box.

   3. (Optional) Click + Add condition and repeat steps 3a–b. All conditions must be true for the segment to match.

4. Under Then, select the Stitch mode to apply to matching requests:

   • SSAI: (Non-just-in-time) Ads are stitched for the entire duration of the video-on-demand media.
   • JIT: (Just-in-time) Ads are stitched immediately before the ad break.

5. Click Save. The segment appears under Stitch mode.

6. (Optional) Repeat steps 1–5 to create additional audience segments for stitch mode.

7. If multiple segments exist, drag the segments into the order JWX should evaluate them. JWX prioritizes segments from top to bottom.

↳ Return to main step 5.

Configure advanced settings

The advanced settings allow you to create A/B test assignments for the ad optimization experience.

Follow these steps to configure the settings:

1. In the top section of the page, click Settings. The Advanced settings page appears.

2. Under A/B test assignment, select an option to determine how viewers are assigned to an ad config when traffic splits.

   Option	Description
   Default	Viewers are assigned by user-agent and IP address. Viewers may switch ad configs if their IP changes. Follow this step: Click Default.
   Custom key	Viewers are assigned by manifest identifier, such as a device or user ID. Each value consistently maps to the same ad config for reliable experiment results. Follow these steps: Click Custom key. From the dropdown menu, select a key type (query/, media/, or header/). In the textbox, enter a key. (Optional) Click + Add another key and repeat steps 1–3 to add another key.

3. Click Save. The Advanced settings panel closes.

↳ Return to main step 6.

Define the JSON configuration

In addition to the visual editor, you can use the JSON editor to review or update the entire ad optimization experience.

The ad optimization groups outcomes under three objects:

• ad_config
• bumpers
• stitch_mode

Each parameter contains an ordered segments array. Every segment combines the conditions in rules with one or more outcomes in results.

Plan the configuration

Before defining the JSON, decide how the experience should behave at request time.

Having these decisions in place helps you define a clear, predictable configuration.

The following example defines an ad optimization experience that:

• Uses weights to split traffic for the Example segment between ad configs A and B
• Uses separate weights in the Default config segment to split unmatched advertising traffic between the same ad configs
• Enables both bumpers when all query, media, and date-time rules in the bumper segment match
• Uses just-in-time stitching when the user query parameter equals 1

Define the JSON configuration

Follow these steps to define the JSON configuration:

1. At the top of the page, click Edit JSON. The Edit ad optimization in JSON panel appears.
2. Update the configuration. See the reference below for more information.
3. Click Save. The JSON editor closes and the visual editor reflects the saved configuration.

JSON sample

{
  "parameters": {
    "ad_config": {
      "segments": [
        {
          "id": "{segment_id_A}",
          "name": "Example segment A",
          "results": [
            {
              "value": "{ad_config_id_A}",
              "weight": 70
            },
            {
              "value": "{ad_config_id_B}",
              "weight": 30
            }
          ],
          "rules": [
            {
              "comparator": "not-equals",
              "lvalue": {
                "key": "example_key",
                "keyspace": "query"
              },
              "rvalue": "0"
            },
            {
              "comparator": "equals",
              "lvalue": {
                "key": "title",
                "keyspace": "media"
              },
              "rvalue": "Example"
            },
            {
              "comparator": "less-than",
              "lvalue": {
                "key": "now",
                "keyspace": "ssai"
              },
              "rvalue": "2027-07-31T13:00:00.000Z"
            }
          ]
        },
        {
          "id": "{segment_id_B}",
          "name": "Default config",
          "results": [
            {
              "value": "{ad_config_id_A}",
              "weight": 75
            },
            {
              "value": "{ad_config_id_B}",
              "weight": 25
            }
          ],
          "rules": []
        }
      ]
    },
    "bumpers": {
      "segments": [
        {
          "id": "{segment_id_B}",
          "name": "Example segment B",
          "results": [
            {
              "value": "both"
            }
          ],
          "rules": [
            {
              "comparator": "not-equals",
              "lvalue": {
                "key": "example_key",
                "keyspace": "query"
              },
              "rvalue": "0"
            },
            {
              "comparator": "equals",
              "lvalue": {
                "key": "producer",
                "keyspace": "media"
              },
              "rvalue": "John Doe"
            },
            {
              "comparator": "less-than",
              "lvalue": {
                "key": "now",
                "keyspace": "ssai"
              },
              "rvalue": "2027-07-01T04:00:00.000Z"
            }
          ]
        }
      ]
    },
    "stitch_mode": {
      "segments": [
        {
          "id": "{segment_id_C}",
          "name": "Example segment C",
          "results": [
            {
              "value": "jit"
            }
          ],
          "rules": [
            {
              "comparator": "equals",
              "lvalue": {
                "key": "user",
                "keyspace": "query"
              },
              "rvalue": "1"
            }
          ]
        }
      ]
    }
  }
}

Top-level configuration

parameters

segments

results

values

rules

lvalue

FAQ