Advertisers: Upgrade Guide

For upgrading from legacy APIs, a migration path is described below.

Upgrading from Insights API

The Insights Reporting API is a REST API for retrieving metrics about offers (referred to as ad groups). To upgrade from the Insights API, modify your endpoint from https://api.tapjoy.com/v1/ad_groups/<id>/insights to https://api.tapjoy.com/graphql. The authorization process remains the same.

Change of id fields

The id used in requests to the Insights API referred to either the primary or secondary tracking offer. In the GraphQL API, primary and secondary offers have been consolidated into a single entity called AdSet. You can query for AdSets using the primary offer id.

For example, below describes how ids get translated from the Insights API to the GraphQL API:

GET /v1/ad_groups/00000000-0000-0000-0000-000000000000/insights
Host: api.tapjoy.com
Authorization: Bearer <OAuth Token>

POST /graphql
Host: api.tapjoy.com
Authorization: Bearer <OAuth Token>

{
  "query": "query { adSet(id: \"00000000-0000-0000-0000-000000000000\") { name } }"
}

Change of metrics

Since primary and secondary tracking offers have been conslidated into a single AdSet, the available insights metrics in the GraphQL API have been designed to reflect the full conversion funnel.

For example, the following Insights API request / response:

GET /v1/ad_groups/00000000-0000-0000-0000-000000000000/insights?start_time=2018-03-06T00:00:00Z&end_time=2018-03-07T00:00:00Z&time_increment=daily
Host: api.tapjoy.com
Authorization: Bearer <OAuth Token>

{
  "data": {
    "00000000-0000-0000-0000-000000000000": {
      "insights": {
        "US": {
          "global_renders": [
            [1520294400, 85069]
          ],
          "paid_clicks": [
            [1520294400, 85069]
          ],
          "global_conversions": [
            [1520294400, 72832]
          ],
          "installs_spend": [
            [1520294400, -1799.45]
          ]
        }
      },
      "metadata": {
        "name": "My Name",
        "platform": "iOS",
        "secondary_offer_id": "00000000-0000-0000-0000-0000000000001"
      },
      "rel": {
        "link": "https://api.tapjoy.com/v1/ad_groups/00000000-0000-0000-0000-0000000000001/insights"
      }
    }
  }
}

...would get translated to the following request / response in the GraphQL API:

query {
  adSet(id: "00000000-0000-0000-0000-000000000000") {
    insights(timeRange: {from: "2018-03-06T00:00:00Z", until: "2018-03-07T00:00:00Z", timeIncrement: DAILY}) {
      timestamps
      reports {
        country
        impressions
        mediaP100WatchedActions
        callToActionClicks
        conversions
        spend
      }
    }
  }
}

{
  "data": {
    "adSet": {
      "insights": {
        "timestamps": [
          "2018-03-06T00:00:00Z"
        ],
        "reports": [
          {
            "country": "US",
            "impressions": [
              85069
            ],
            "mediaP100WatchedActions": [
              72832
            ],
            "callToActionClicks": [
              24662
            ],
            "conversions": [
              493
            ],
            "spend": [
              1799450000
            ]
          }
        ]
      }
    }
  }
}

As you can see, in order to build the entire conversion funnel you would have also had to request the insights for the secondary tracking offer in the legacy Insights API.

In the GraphQL API, the metrics have all been combined via the AdSet. These metrics can be translated to their legacy equivalent like so:

GraphQL API metric Insights API metric(s)
Impressions global_renders / paid_clicks (Primary)
Media P100 Watched Actions global_conversions (Primary), global_renders / paid_clicks (Secondary)
Call-to-action Clicks n/a
Conversions global_conversions (Secondary)
Spend installs_spend (Primary / Secondary)

Please contact your Tapjoy AM or support if you have any questions.