Overview

If you are an iOS app publisher who uses iAd to generate advertising revenue, you can use the iAd Publisher API to efficently track the performance and revenue generated from the advertising in your apps. The iAd Publisher API provides programmatic access to your iAd account data, allowing you to pull reporting data from iAd for integration into your own systems for analysis. The API also allows you to report on revenue by device class and revenue by ad format, which are not available through the web portal.

The iAd Publisher API is available to all iAd publishers with admin access who have enabled iAd integration in their apps.

The iAd Publisher API uses the same authentication system as the iAd Workbench API. To request and download the API keys, tokens, and certificates required to access iAd, you will need an iAd Workbench account. If you do not not already have an iAd Workbench account:

1. Go to iadworkbench.apple.com and log in with your Apple ID.

2. Provide your contact information and create your Workbench account.

To request and download the API keys, tokens, and certificates required to access the iAd server:

1. Log in to iAd Workbench.

2. Click on the dropdown arrow next to your account name near the top right.

3. Choose API from the popup menu.

4. Enter the displayed security code.

5. Press the Download New Keys button.

6. Save the Zip file in an approprate location.

Implement your utilization of the iAd Publisher API by following the details proved in “API Concepts” and following sections of this document and use this end point URL:

• https://iadapi.apple.com/publisher/v1

This document describes the v1 URL of iAd Publisher. For more details, see “Versioning of the API” below.

API Basics

• The iAd Publisher API 1.0 supports JSON-RPC 2.0 payloads over HTTP POST. This allows you to programmatically access performance data from your iAd account.

• A request is a JSON-RPC 2.0 payload in an HTTP POST request with the Content-Type header of “application/json”.

• A response is a JSON-RPC 2.0 payload in an HTTP response request with the Content-Type header of “application/json” and is encoded as UTF-8.

• The request payload contains the method name and the method parameters, which in this API is a single Dictionary object.

• The response payload contains the result, which in this API must be a single Dictionary object.

• Any Array (also called a Collection or List) should contain uniform types. Within the JSON-RPC Dictionary objects, all keys must be String objects and the following primitives and objects may be represented (in nested forms): String, Number, Array, Dictionary, Boolean, NULL. For example, an Array may contain String objects, Number objects, other Array objects, or other Dictionary objects, which in turn may have other primitive types within them. Dictionary objects may have any primitive type for a given value, but the keys must be strings.

Authentication and Authorization

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

• API access is available to iAd Workbench advertiser accounts. You must create an iAd Workbench advertiser account to access the API.

• Users of the iAd Publisher API need to have admin access within iAd Workbench to be able to download client side SSL certificate signed by iAd, a client side private key, and an access token.

• The client side SSL certificate, Key, and access token should be used to call the InitSession method. This call authenticates, establishes a secure connection, and provides the session ID required to make API calls.

• As a security measure, three successive invalid authentication attempts will lock the API access for a minimum of four hours.

Versioning of the API

iAd Publisher API v1 is read-only. It allows you to generate reports on the performance and revenue generated by your iAd-enabled apps. The API version is specified in the URL, e.g., https://iadapi.apple.com/publisher/v1 is the URL for the v1 version.

If new features are added to the iAd Publisher API, as long as they are backward compatible, the URL will remain the same. If new features are ever added that are not backward compatible, a new URL will be introduced that supports those features.

Invoking the API

• There is no additional charge to use the Publisher API. However, there is a limit of 10,000 API calls per day (Midnight to Midnight, UTC), total for all iAd APIs, including Workbench API and Publisher Reporting API. If you expect to make more API calls than this, consult your iAd account representative.

• Because the communication protocol for the iAd Publisher API is JSON RPC 2.0, any language can be used to develop client programs.

• Request objects must follow the JSON-RPC 2.0 specification and must include the following fields:

  • jsonrpc: A string specifying the version of JSON-RPC protocol. The string value must be exactly “2.0”.

  • method: A string containing the name of the method to be invoked.

  • id: A unique identifier established by your client program. It must be a string that ideally is unique for each call. The server will reply back using the same ID. If the input request id is unique, the output response will be uniquely assoctiated with the call that generated it. This field must be specified.

  • params: An array of name-value pairs of named parameters and their corresponding values.

• Response objects follow the JSON-RPC 2.0 specification and include the following fields:

  • jsonrpc: A string specifying the version of JSON-RPC protocol, which is exactly “2.0”.

  • id: This will be provided in every response and is the same as the ID sent in the request object.

  • result: In almost all cases, the result includes a Success attribute, a boolean value of true or false indicating success or failure of the API call. If Success is true, then result includes the response to the method request. If Success is false, then result includes an error message and an error code.

API Concepts

Session Management

{

   "method":"InitSession",

   "id": "RequestNo-001",

   "params":{

      "accessToken":"1234567890"

   },

   "jsonrpc":"2.0"

}

{ "id": "RequestNo-001",

  "result": {

    "SessionId": "44e5b59211ae0da9c9739b0866936ca94301d444"

  },

  "jsonrpc": "2.0"

}

Obtaining Report Metrics

{

  "method": "GetAppMetrics",

  "id": "1001",

  "params": {

    "SessionId": "3ee7bb3fe686cae2415b99b63399bd20b4269bd0",

    "AppIds": [

      "456789123",

      "345678912"

    ],

    "StartTime": "2015-04-05"

    "EndTime": "2015-04-05",

  },

  "jsonrpc": "2.0"

}

{

  "id": "1001",

  "result": {

    "Metrics": [

      {

        "AppId": "900000002",

        "AppName": "AnonApp",

        "Country": "US",

        "CreativeType": "Banner",

        "DeviceClass": "iPhone",

        "Date": "2015-03-05 00:00:00.0",

        "Taps": "0",

        "eCPM": "0.00",

        "Impressions": "0",

        "TTR": "0.00",

        "Revenue": "0.00",

        "GlobalRequests": "99999",

        "iAdCountryRequests": "99999",

        "iAdFillRate": "0.00"

      },

      {

        "AppId": "900000002",

        "AppName": "AnonApp",

        "Country": "US",

        "CreativeType": "Banner",

        "DeviceClass": "iPad",

        "Date": "2015-03-05 00:00:00.0",

        "Taps": "0",

        "eCPM": "0.00",

        "Impressions": "0",

        "TTR": "0.00",

        "Revenue": "0.00",

        "GlobalRequests": "88888",

        "iAdCountryRequests": "88888",

        "iAdFillRate": "0.00"

      },

      {

        "AppId": "900000001",

        "AppName": "LightRight",

        "Country": "US",

        "CreativeType": "Banner",

        "DeviceClass": "iPad",

        "Date": "2015-03-05 00:00:00.0",

        "Taps": "0",

        "eCPM": "0.00",

        "Impressions": "0",

        "TTR": "0.00",

        "Revenue": "0.00",

        "GlobalRequests": "77777",

        "iAdCountryRequests": "77777",

        "iAdFillRate": "0.00"

      }

    ],

    "Success": true

  },

  "jsonrpc": "2.0"

}