Campaign Management API for News Publishers — Overview

Apple News publishers have the ability to launch, monitor, and report on direct-sold and house advertising campaigns via “Workbench for News Publishers”.

The Campaign Management API for News Publishers described in this document provides programmatic access to Apple’s campaign management API server, where you can use your own tools and programs to do the same kinds of tasks as you would do with the Workbench:

Access, Authentication, and Authorization

The Campaign Management API for News Publishers is available to all Apple News publisher accounts that have access to News Publisher tools on Workbench.

Client side SSL certificate is used to authenticate the user. An access token provides authorization to all of the API.

To access the Advertising Platforms API server, you can request and download the required API keys, tokens, and certificates from the Workbench site.

  1. Click on the dropdown arrow next to your account name near the top right and choosing Account from the dropdown menu.

  2. Select the API tab under the page title.

  3. Click the button to “Create Key”.

  4. Name your key and assign access to a tool set.

  5. Enter the “Captcha” text.

  6. Confirm and download your key in a ZIP file.

You will receive:

The certificate that you download is a PEM file, which is typically used with Python. The following commands use the publically available openssl and keytool utilities to convert the PEM certificate to P12 or JKS formats as needed. Use the first command to convert your PEM-format certificate to a P12-format certificate, typically used with RESTful systems. Use the second to convert that P12-format certificate to a JKS-format certificate, typically used with Java.

openssl pkcs12 -export -in certificate.pem -inkey private_key.key -out certificate.p12 -name “<NAME>"
keytool -v -importkeystore -srckeystore certificate.p12 -srcstoretype PKCS12 -destkeystore certificate.jks -deststoretype JKS

Use your client-side SSL certificate, key, and access token when you call the InitSession method. This call authenticates, establishes a secure connection, and provides the session ID required to make further API calls.

As a security measure, ten successive invalid authentication attempts will lock the API access for a minimum of five hours.

API Endpoint

Implement your API-based app by following the API Method Reference in this document and use the following end point URL:

This document describes the /v1 version of the Apple Advertising Platforms News Publishers API.

API Basics

Versioning of the API

Versioning is managed through the URL. When new features are added to the News Publishers API, as long as they are backward compatible, the URL will remain the same. If new features are added that are not backward compatible, a new URL will be introduced that supports those features and the unchanged features.

Invoking the API

API Concepts

This section provides brief descriptions of the API interaction process and workflow phases, at a conceptual level.

Authentication

Before you can interact with the News Publishers API, you must provide your credentials, access token, and certificate, and obtain a session ID. Your session ID is used for the duration of your API interaction session.

Helper Methods for Campaign Creation Workflow

These methods provide data that is not specific to individual campaigns. This data includes campaign categories, available ad types, ads you have created in Producer, targeting parameters, and time zones.

Campaign and Line Creation

These methods allow you to create campaigns and lines, using the information provided by helper methods, as appropriate, upload ads, associate ads to specific lines, and submit your campaign.

Managing Campaign Methods

This section includes methods that allow you to update campaigns and lines and to activate and pause campaigns, lines, and ads.

Inventory Methods

Ad placement inventory consists of the ad locations that are available for sale. For privacy and security, these are aggregated and tracked statistically. The methods in this section allow you to check, reserve, and unreserve available inventory.

Reporting Methods

You can use the API to download reporting data for your campaigns lines, and ads that were created using the Workbench UI.

  • To get campaign summary or details, use the methods GetCampaignSummary or GetCampaignDetails.

  • To get line or ad details, use the methodsGetLineDetails or GetAdDetails.

  • To get the metrics, use the following methods based on the level at which you need the data:

    • GetCampaignMetrics

    • GetLineMetrics

    • GetAdMetrics