Publisher Report Development Guide Overview

This documentation provides a detailed walkthrough for publishers integrating with Atlas Reporting API. The following steps are required to gain API access:

Once API access is in place, development of the following items is required:

Appendix - following API is supported, but it requires more involvment from development teams.

User permission and token

App creation and token generation

Publishers are required to create a Facebook app, which will be provisioned to make Atlas API calls using the Facebook Graph API Platform.

To generate an FB App ID, go to https://developers.facebook.com/apps and select “Create a new app"

Access tokens are required to access data or make changes to objects via the Atlas API. When API access has been granted to your app, your app is authorized to act on behalf of certain users. You can get the access token of the app's users by making an HTTP GET request.

An example of the request:

https://graph.facebook.com/<API_VERSION>/<APP_ID>?access_token=<APP_ID>|<CLIENT SECRET>&fields=manageable_users{name,access_token} 

Response:

{
   "manageable_users": {
      "data": [
         {
            "id": "123456789",
            "name": "User Name"
            "access_token": "<ACCESS TOKEN>"
         }
      ],
      "paging": {
         "cursors": {
            "before": "MTQwOTk3NDU5OTI5MjkyOQ==",
            "after": "MTQwOTk3NDU5OTI5MjkyOQ=="
         }
      }
   },
   "id": "<APP ID>"
}

If you get unknown error from the API, it is because your app is still in sandbox mode. Go to the app settings, status section and make the app public.

API Permission

A user access token with Atlas API capability is required to have publisher report API access. The Atlas Solutions Consultant teams can help with assigning this capability to your app.

An app and a user pair defines the token. The user defines the permission model and ensures, publisher is not pulling the data which they do not have access to. App is a mechanims to make the API call. Atlas Solutions Consultant team is responsible for creating the user and setting up the permission model for your the entire Atlas hierarchy.

If you have any issues or questions during or after integration, you can reach out to your Atlas contact.

Integration use cases

Pulling data as a publisher

As a publisher, you can pull Atlas reports to see impression, click, conversion data for campaigns that uses you as a Publisher and all affiliated sites within Atlas.

Pulling data as a partner

If you are a partner working with multiple publishers, you will be able to pull a report for each publisher.

  • The user token: we will create a user for each publisher you work with. When you generate the token, you will see list of users with their access token. We will provide you mapping of user to publisher. In this case one user will hold the access to one publisher.
  • The report flow: the reporting flow will be same as if you are a single publisher. Only difference is that, you will need to iterate through all the publishers you work with.

Reporting workflow

The workflow involves following steps:

  1. Creating a report - do this step from the Atlas Solutions user interface. We do support report creation via API, which requires more involvement.

  2. Generate report runs - schedule the report run to create report run. Some reports may take a while to complete and you can check the status of a report run. Refer to the report run and reportrun status object documentation for details.

  3. Read report run data - After the report run is completed, you can read the report run data. Please refer to the report run data api for details.

API Integration

Create report from UI

Login to your atlas solutions app and click on the reports from the left hand navigation view. On the right you will see create option to create a new publisher report. Fill out the required fields as shown below.

In order to schedule a report, you need have report_id first. You can get all the reports created for a publisher by making a GET request to publisher end point.

Example GET request:

https://graph.facebook.com/<PUBLISHER_ID>/reports?fields=id,name

Example response:

{
  "data": [
    {
      "id": "11182200954731",
      "name": "Report with conversion columns"
    },
    {
      "id": "11182200959305",
      "name": "report without action tags"
    },
    {
      "id": "11182200959379",
      "name": "test report w/net media cost"
    },

  ],
  "paging": {
    "cursors": {
      "after": ""
    },
    "next": "https://graph.facebook.com/v2.5/11182200774314/reports?access_token=<ACCESS_TOKEN>"
  }
}

Schedule the report

You can schedule reports to execute at a future date and time. It can be set up as a recurring event with values like daily, weekly, monthly or once and you can specify the minute of the day when the report is supposed to execute.

Refer to the Atlas Report Schedule API Reference Document to get all the field definition.

Example POST request to create weekly scheduled report:

https://graph.facebook.com/<API_VERSION>/<REPORT_ID>/report_schedules?report_schedules=
[
    {
        "is_active": true,
        "date_range": {
            "begin_date": "2015-8-28 12:0:0",
            "end_date": "2015-9-28 12:0:0",
            "time_zone": "America/Los_Angeles"
        },
        "recurrence_type": "weekly",
        "recurrence_value": 2,
        "minute_of_day": 420
    }
]

Example Request for once scheduled report:

https://graph.facebook.com/<API_VERSION>/<REPORT_ID>/report_schedules?report_schedules=
[
    {
        "is_active": true,
        "date_range": {
            "begin_date": "2015-8-28 11:49:0",
            "end_date": "2015-8-28 11:49:0",
            "time_zone": "America/Los_Angeles"
        },
        "recurrence_type": "once",
        "recurrence_value": 0,
        "minute_of_day": 709
    }
]

Response:

{
  "data": [
    {
      "id": "11182201039885",
      "success": true
    }
  ]
}

If you want to change the schedule time, you can make a POST call to report_schedules edge on the report node. Make sure you provide all the report schedule fields when constructing the call. See example below:

https://graph.facebook.com/<API_VERSION>/<REPORT_ID>/report_schedules
report_schedules=
   [{
      "date_range": {
        "begin_date": "2015-10-28T11:21:00-0700",
        "end_date": "2015-08-28T11:21:00-0700",
        "time_zone": "America/Los_Angeles"
      },
      "id": "11182201032772",
      "minute_of_day": "720",
      "recurrence_type": "weekly",
      "recurrence_value": "2",
    }]

If you just want to update the recurrence type or the minute of the day. You do not need to provide date_range.

The reponse:

{
  "data": [
    {
      "id": "11182201032772",
      "success": true
    }
  ]
}

Retrieve report run details

For pulling the report run data, you need to provide the report_run_id. You also need to make sure you are retrieving the right report data for the right report run instance. You can come do this by writing a business logic to connect the report run create date to the report scheduled date. The report run create date basically means when the report run was completed.

Once the report starts executing, you can check the completion status of the report run using the report_id you retrieved from the above API request. The status is particularly useful for reports running for long periods of time.

Report run status possible values:

ValueDescription

ReportRunStatus.Scheduled

Refers to scheduled status of report run

ReportRunStatus.Running

Refers to running status of report run

ReportRunStatus.Completed

Refers to completed status of report run

ReportRunStatus.Error

Refers to error status of report run

ReportRunStatus.Timeout

Refers to timeout status of report run



Example GET request to retrieve id, status and the date,

https://graph.facebook.com/<API_VERSION>/<REPORT_ID>/report_runs?fields=id,status,created_date

The response will look something like this:

{
  "data": [
    {
      "id": "11182201008255",
      "status": "completed",
      "created_date": "2015-07-20T23:45:00+0000"
    },
    {
      "id": "11182201008259",
      "status": "running",
      "created_date": "2015-07-21T23:45:00+0000"
    },
    {
      "id": "11182201008267"
      "status": "running",
      "created_date": "2015-07-22T23:45:00+0000"
    }
  ]
}

Download report data

You can download the report run data through the download url provided by the API. The report is generated in a csv or xlsx format depending on how to defined the format during report cration.

Example request:

https://graph.facebook.com/<API_VERSION>/<REPORT_RUN_ID>/data?filename=data

Response:

The response will be a file download generated named data.csv/data.xlsx

A sample custom report may look like below:

Appendix

Retrieve filterable objects for a publisher

When you create a report, you can provide the object ids that you want to filter with. These objects can be company, branch, client, advertiser, campaign, publisher, sites or action tags. See the report creation API example to see how these ids can be passed.

  • To filter by objects, set the values for the filters key within definition key, when creating a report.
  • To filter by action tag, set the values for the action_tag_ids key within definition key, when creating a report.

To get list of sites within a publisher: https://graph.facebook.com/v2.4/<PUBLISHER_ID>/sites

To get list of companies using a publisher: https://graph.facebook.com/v2.4/<PUBLISHER_ID>/companies

To get list of branches within a company: https://graph.facebook.com/v2.4/<COMPANY_ID>/branches

To get list of clients for a branch or a company__ https://graph.facebook.com/v2.4/<BRANCH_ID>/clients https://graph.facebook.com/v2.4/<COMPANY_ID>/clients

To get list of advertiser for a client: https://graph.facebook.com/v2.4/<CLIENT_ID>/advertisers

To get the list of campaigns for an advertiser: https://graph.facebook.com/v2.4/<ADVERTISER_ID>/campaigns

To get the list of actions tags shared with a publisher: https://graph.facebook.com/v2.4/<PUBLISHER_ID>/shared_action_tags

Read the Atlas Publisher Node reference doc to learn more about Publisher APIs.

As a publisher you should know your publisher id withing Atlas. If you are not sure what this ID is, ask your Atlas Solutions Consultant contact.

Create Publisher Report from API

Create publisher reports by making an HTTP POST request to publisher end point. The post request will create a Report object and returns the Report Object ID in the response. View following API docs to see app possible values used in the example:

The required fields and validation:

  • The version field has to be Integer.
  • You need to provide a valid publisher_id in the filter field within the report definition. You can provide mulitple publisher ids to get aggregate data for multiple publisher, given that you have access to the data for that publisher.
  • You need to provide a company_id in the filter field within the report definition. You can provide mulitple company_ids to get aggregate data.
  • For the filter definition if you want to filter by any object, you must make sure that the parent id is provided. For example, if you want to filter by a client, you must provide a branch id and company id. Because branch is parent of client and company is parent of branch. See following for the parent child relation within Atlas hierarchy.

Example Request:


https://graph.facebook.com/<API_VERSION>/<PUBLISHER_ID>/reports? reports= [{ "name":"Test Publisher Report", "version":1, "description":"", "definition":{ "column_definitions":[ { "area":"serving", "attribution_model":null, "category":"standard", "key":"ad_id", "name":"Ad ID", "aggregation_usage":"dimension" }, { "area":"serving", "attribution_model":null, "category":"standard", "key":"ad_name", "name":"Ad Name", "aggregation_usage":"dimension" }, { "area":"serving", "attribution_model":null, "category":"standard", "key":"advertiser_id", "name":"Advertiser ID", "aggregation_usage":"dimension" }, { "area":"serving", "attribution_model":null, "category":"standard", "key":"advertiser_name", "name":"Advertiser Name", "aggregation_usage":"dimension" }, { "area":"attribution", "attribution_model":"last_touch", "category":"standard", "key":"counters_clicks", "name":"Clicks", "aggregation_usage":"metric" }, { "area":"attribution", "attribution_model":"last_touch", "category":"standard", "key":"clickthrough_rate", "name":"Clickthrough Rate %", "aggregation_usage":"metric" } ], "date_range":{ "type":"relative", "date_unit":"day", "quantity":"0", "time_zone":"America/New_York" }, "time_zone":"America/New_York", "report_type":"publisher", "crosstab_columns":[], "action_tag_ids":[], "filters":{ "advertiser_ids":["11077200770662"], "branch_ids":["11077200629234"], "campaign_ids":["11077201127917"], "client_ids":["11077200629235"], "company_ids":["11077200629233"], "publisher_ids":["11182200774314"], "site_ids":["11182200828329"] } }, "file_format":"xlsx", "is_email_enabled":false, "email_addresses":[], "email_suffix":"" }]

Example Response:

{
  "data": [
    {
      "id": "11182201008254", 
      "success": true
    }
  ]
}

Generate ad hoc report run

You can generate ad hoc report runs for all the reports defined within a publisher or for a specific report defined for a publisher by making an HTTP POST request to publisher or report end point report_runs edge.

Refer to the Atlas Report Run API Reference Document to get all the field definition.

Example POST request to generate report run for all publisher reports:

https://graph.facebook.com/<API_VERSION>/<PUBLISHER_ID>/report_runs?
report_runs=
[{
  "name":"Test Publisher Report",
  "version":1,
  "description":"",
  "definition":{
    "column_definitions":[
    {
      "area":"serving",
      "attribution_model":null,
      "category":"standard",
      "key":"ad_id",
      "name":"Ad ID",
      "aggregation_usage":"dimension"
    },
    {
      "area":"serving",
      "attribution_model":null,
      "category":"standard",
      "key":"ad_name",
      "name":"Ad Name",
      "aggregation_usage":"dimension"
    },
    {
      "area":"serving",
      "attribution_model":null,
      "category":"standard",
      "key":"advertiser_id",
      "name":"Advertiser ID",
      "aggregation_usage":"dimension"
    },
    {
      "area":"serving",
      "attribution_model":null,
      "category":"standard",
      "key":"advertiser_name",
      "name":"Advertiser Name",
      "aggregation_usage":"dimension"
    },
    {
      "area":"attribution",
      "attribution_model":"last_touch",
      "category":"standard",
      "key":"counters_clicks",
      "name":"Clicks",
      "aggregation_usage":"metric"
    },
    {
      "area":"attribution",
      "attribution_model":"last_touch",
      "category":"standard",
      "key":"clickthrough_rate",
      "name":"Clickthrough Rate %",
      "aggregation_usage":"metric"
    }
    ],
    "date_range":{
      "type":"relative",
      "date_unit":"day",
      "quantity":"0",
      "time_zone":"America/New_York"
    },
    "time_zone":"America/New_York",
    "report_type":"publisher",
    "crosstab_columns":[],
    "action_tag_ids":[],
    "filters":{
      "advertiser_ids":["11077200770662"],
      "branch_ids":["11077200629234"],
      "campaign_ids":["11077201127917"],
      "client_ids":["11077200629235"],
      "company_ids":["11077200629233"],
      "publisher_ids":["11182200774314"],
      "site_ids":["11182200828329"]
    }
  },
  "file_format":"xlsx",
  "is_email_enabled":false,
  "email_addresses":[],
  "email_suffix":""
}]

Example POST request to generate report run for a given report:

https://graph.facebook.com/<API_VERSION>/<REPORT_ID>/report_runs?
report_runs=
[{
  "name":"Test Publisher Report",
  "version":1,
  "description":"",
  "definition":{
    "column_definitions":[
    {
      "area":"serving",
      "attribution_model":null,
      "category":"standard",
      "key":"ad_id",
      "name":"Ad ID",
      "aggregation_usage":"dimension"
    },
    {
      "area":"serving",
      "attribution_model":null,
      "category":"standard",
      "key":"ad_name",
      "name":"Ad Name",
      "aggregation_usage":"dimension"
    },
    {
      "area":"serving",
      "attribution_model":null,
      "category":"standard",
      "key":"advertiser_id",
      "name":"Advertiser ID",
      "aggregation_usage":"dimension"
    },
    {
      "area":"serving",
      "attribution_model":null,
      "category":"standard",
      "key":"advertiser_name",
      "name":"Advertiser Name",
      "aggregation_usage":"dimension"
    },
    {
      "area":"attribution",
      "attribution_model":"last_touch",
      "category":"standard",
      "key":"counters_clicks",
      "name":"Clicks",
      "aggregation_usage":"metric"
    },
    {
      "area":"attribution",
      "attribution_model":"last_touch",
      "category":"standard",
      "key":"clickthrough_rate",
      "name":"Clickthrough Rate %",
      "aggregation_usage":"metric"
    }
    ],
    "date_range":{
      "type":"relative",
      "date_unit":"day",
      "quantity":"0",
      "time_zone":"America/New_York"
    },
    "time_zone":"America/New_York",
    "report_type":"publisher",
    "crosstab_columns":[],
    "action_tag_ids":[],
    "filters":{
      "advertiser_ids":["11077200770662"],
      "branch_ids":["11077200629234"],
      "campaign_ids":["11077201127917"],
      "client_ids":["11077200629235"],
      "company_ids":["11077200629233"],
      "publisher_ids":["11182200774314"],
      "site_ids":["11182200828329"]
    }
  },
  "file_format":"xlsx",
  "is_email_enabled":false,
  "email_addresses":[],
  "email_suffix":""
}]