Guides and Sample Code

Developer

Advertising Guide for News Publishers

On This Page

Using Third-Party Ad Tags

Serving third-party ads

Third-party ad tags can be used to serve Standard Banner, Double Banner, Large Banner, Medium Rectangle Banner (MREC), Interstitial Banner, IAB 300x250 Banner, and IAB 728x90 Banner ads only on iOS 10.3 and above.

Third-party served ads should adapt to changes in point sizes for portrait and landscape orientations. A single ad tag must be used to render for both portrait and landscape orientation for the respective device type. (i.e. One tag per format for all supported iPhone devices in portrait and landscape orientation.)

Third-party Interstitial ads should be coded as a banner rather than a typical MRAID interstitial. The Apple News Ad SDK will always return “inline” when the MRAID.getPlacementType method is called. Interstitial ads on Apple News do not have a standard close button to exit out of the ad experience. Users can exit out of the Interstitial ad on the News app by swiping left or right to the next article.

MRAID implementation

Apple News Advertising SDK implements a subset of MRAID 1.0 as a standard mraid.js that can be called by the ad. All tags must be MRAID compliant. Supported methods and events are listed below.

Supported MRAID 1.0 methods

  • addEventListener

  • close

  • expand (two part only)

  • getExpandProperties

  • getPlacementType

  • getState

  • getVersion

  • isViewable

  • open

  • removeEventListener

  • setExpandProperties

  • createCalendarEvent

Supported MRAID 1.0 events

  • error

  • ready

  • stateChange

  • viewableChange

Whitelisting

Ads requested by Apple News will be routed through an Apple-hosted proxy server for privacy purposes. This means that all ads served on Apple News will come from an Apple IP address, therefore you need to make sure this traffic is not identified as bots or DDOS by your servers. The ideal way to solve this is to whitelist all IP addresses beginning with 17 (e.g. 17.*.*.*), which are all owned by Apple.

Additional ad unit development details

While the ads are loaded in a fairly standard web view (WKWebView), there are important constraints that must be considered when developing ads for use on Apple News.

  1. All paths to resources that the ads load must be absolute (complete) URLs, not relative paths.

  2. Use of iframes is not supported. When ads are loaded in Apple News, they cannot create or use iframes at any time; it will fail the ad load. The MRAID object is only accessible via the document’s mainframe.

  3. SSL serving is required. All ads must be SSL compliant.

  4. Taps are supported using MRAID.open method or anchor tags <a href>.  Use of Window.open will cause the clicks to fail. 

  5. A maximum of 100 requests per impression is allowed. This includes all pixels, JS, image, etc. requests. Any requests beyond the allowed limit will be ignored.

  6. The values of window.location and document.location will return empty in javascript code. Typical code which uses window.location or window.location.protocol to determine whether resources should be loaded using https:// or http:// as a prefix will therefore fail to correctly request resources via https:// as required by Apple specifications.

In-banner features

Supported in-banner features

  • HTML5 JS/ CSS Animation

  • Tap — activates a control or selects an item

  • Flick — scrolls or pans quickly

  • Drag — move an element from side to side or drag an element across the display banner’s interaction space.

Unsupported features

To optimize the user’s experience and ensure security and privacy, some device features are blocked by Apple News Ad SDK.

  • Accelerometer

  • Gyroscope

  • In-banner forms

  • Tap to SMS/ Call/ Email

  • Camera access

  • In-banner video/ audio

  • Device location

Supported vendor(s)

  • Bonzai

  • Celtra

  • Polar

  • Sizmek

Third-party ad checklist

  • Absolute URLs only.

  • Apple IPs (17.*) whitelisted or not blocked.

  • No iframes.

  • SSL compliant.

  • All clicks using MRAID.open() or <a href>.

  • Less than 100 requests per impression.

  • All ads are to spec in portrait and landscape mode.

  • Apple News compliant interstitial ads (placmentType = inline).

  • Expandable ads.

    • No custom close.

    • Two-Part expand.

Supported macros

  • %%cachebuster%% — replaced with a random number for cache busting.

  • %%APPLE_NEWS_CHANNEL_NAME%% — replaced with the channel name.

  • %%APPLE_NEWS_CHANNEL_ID%% — replaced with channel id.

  • %%APPLE_NEWS_CAMPAIGN_NAME%% — replaced with campaign name.

  • %%APPLE_NEWS_CAMPAIGN_ID%% — replaced with campaign id.

  • %%APPLE_NEWS_LINEITEM_NAME%% — replaced with the line name.

  • %%APPLE_NEWS_LINEITEM_ID%% — replaced with the line id.

  • %%APPLE_NEWS_CREATIVE_SIZES%% — replaced with the width and height the ad format is expected to return. This macro can return more than one value if the dimension of portrait and landscape units are different.

Third-party ad notes

Using third-party ad tags through Workbench may result in higher than expected third-party ad-serving costs due to differences between Apple standards and other third-party reporting metrics. You are responsible for any fees charged for third-party ad serving.

Within Workbench the following metrics are recorded:

  • Viewable Impressions: When 100% of the banner is fully displayed on screen for one second or more.

  • Requested Impressions: When an initial request is made through the Apple proxy to a third-party server.

Apple bases its campaign delivery and pacing on Viewable Impressions. There may be variances when comparing third-party reporting metrics because viewability standards vary among third-party vendors. Requested Impressions may be more closely aligned with a third-party vendor’s standard impression metric since it is based on the initial request, and not Apple’s viewability standards.

Examples of third-party ad tags

Listing 11-1Sample Celtra ad tag
  1. <script src="mraid.js"></script>
  2. <div class="celtra-ad-v3">
  3. <!-- externalLineItemId = raw %%APPLE_NEWS_LINEITEM_ID%% -->
  4. <!-- externalLineItemName = raw %%APPLE_NEWS_LINEITEM_NAME%% -->
  5. <!-- externalSupplierId = raw %%APPLE_NEWS_CHANNEL_ID%% -->
  6. <!-- externalSupplierName = raw %%APPLE_NEWS_CHANNEL_NAME%% -->
  7. <!-- externalCampaignId = raw %%APPLE_NEWS_CAMPAIGN_ID%% -->
  8. <!-- externalCampaignName = raw %%APPLE_NEWS_CAMPAIGN_NAME%% -->
  9. <!-- applenews_creative_size = raw %%APPLE_NEWS_CREATIVE_SIZES%% -->
  10. <img src="data:image/png,celtra" style="display: none" onerror="
  11. (function(img) {
  12. var params = {'clickUrl':'','clickEvent':'advertiser','externalAdServer':'AppleNews','tagVersion':'4'};
  13. [].slice.apply(img.parentNode.childNodes).forEach(function(n) { var decfs = { urldecode: decodeURIComponent, htmldecode: function(v) { var d = document.createElement('div'); d.innerHTML = v; return d.textContent; }, eval: function(v) { return eval(v); }, raw: function(v) { return v; } }; var m; if (n.nodeType == 8 &amp;&amp; (m = n.textContent.match(/^&#92;s+([&#92;w.]+)(&#92;[.+&#92;])?&#92;s+=&#92;s+(&#92;w+)&#92;s+(.*)$/i))) { try { params[m[1]+(m[2] || '')] = decfs[m[3]](m[4].replace(/^&#92;s+|&#92;s+$/g, '')); } catch (e) {} } });
  14. var req = document.createElement('script');
  15. req.id = params.scriptId = 'celtra-script-' + (window.celtraScriptIndex = (window.celtraScriptIndex||0)+1);
  16. params.clientTimestamp = new Date/1000;
  17. params.clientTimeZoneOffsetInMinutes = new Date().getTimezoneOffset();
  18. params.hostPageLoadId = window.celtraHostPageLoadId = (window.celtraHostPageLoadId || (Math.random()+'').slice(2));
  19. var src = ((window.location.protocol == 'https:' || /iP(ad|hone|od).*OS ([0-9_]+)/.test(navigator.userAgent)) ? 'https' : 'http') + '://ads.celtra.com/12345678/mraid-ad.js?';
  20. for (var k in params) {
  21. src += '&amp;' + encodeURIComponent(k) + '=' + encodeURIComponent(params[k]);
  22. }
  23. req.src = src;
  24. img.parentNode.insertBefore(req, img.nextSibling);
  25. })(this);
  26. "/>
  27. </div>

Previewing ads through Workbench

There are 2 ways to preview how your ads will render and function through Workbench:

  • Preview on Workbench: You can preview your ad creative on the Create Ad page as you’re assembling your ad creative.

  • Previewing on device: To truly ensure that your ad is rendering and behaving as expected, you should preview your ad on a device. On Workbench, simply send yourself a link of your ad creative to open and review on your desired device.