@custom

Description

The @custom context query simply acts as a namespace for any custom attribute that you may want to apply to your ad either through your own javascript or through the trafficking settings of the ad.

Example Usage

It's important to note, that while other context values are applied to the ad dynamically, that is not the case for @custom context queries. @custom context queries are applied through trafficking settings or through custom javascript.

Variance testing is a great example of using a custom context. In the below example, a custom context called version is used to mark different versions of the ad and style them accordingly.

When the ad is trafficked, three separate tags can be generated with "context overrides" that explicitly set the value of version to a, b, and c. Those tags can then be run on a rotation to have the ad display each versions and optimized accordingly throughout the flight.

In the below example, styles for version: a would apply when the tag used a context override to set the custom version to a. Styles for version: b would apply when the tag used a context override to set the custom version to b. And styles for version: c would apply when the tag used a context override to set the custom version to c.

CSS Example

.component {
	background-color: transparent;
  
  @custom (version: a) {
  	background-color: red;
  }
  
  @custom (version: b) {
  	background-color: green;
  }
  
  @custom (version: c) {
  	background-color: blue;
  }
}

Setting Custom Contexts via Javascript

In certain situations you may have a very complex set of rules that would describe the context you are trying to style against.

Perhaps, you needed the ad to look a certain way when the user is in Chicago, using a tablet, running iOS, and viewing the ad at fullscreen. That would be a lot of context queries to write in your CSS!

A more efficient way would be to use the @custom context query and then set the value of that context using javascript as shown below:

CSS

.component {
	background-color: red;
}

.button {
	background-color: white;
}

@custom (complexRule: true) {
	.component {
  	background-color: white;
  }
  .button {
  	background-color: red;
  }
}

By itself, the code nested within the @custom context query would never match. But with some custom javascript, we can tell the ad when this rule should match using the ad.set(attributeName) method as show below.

JavaScript

ad.on('change', function() {
  // Get all the values everytime the ad changes
  var city = ad.get('locationCity'),
      device = ad.get('deviceType'),
      os = ad.get('deviceOsFamily'),
      adWidth = ad.get('adWidth'),
      adHeight = ad.get('adHeight'),
      viewportWidth = ad.get('deviceViewportWidth'),
      viewportHeight = ad.get('deviceViewportHeight');
  
  // First check if the ad is fullscreen
  if (adWidth === viewportWidth && adHeight === viewportHeight) {
  	// Now check if the ad meets the other requirements
    if (city === 'chicago' && device === 'tablet' && os === 'ios') {
      // If both tests pass, then set the custom context of 'contextRule' tp true
      ad.set('customComplexRule', 'true');
    } else {
      // If it doesn't pass, set custom context to false
      ad.set('customComplexRule', 'false');
    }
  } else {
    // If it's not fullscreen, then set custom context to false
    ad.set('customComplexRule', 'false');
  }
});