Working with RollWorks Playbooks

RollWorks customers can utilize the NextRoll API to manage their Playbooks.

For example:

• Fetch your list of Playbooks and their metadata

• Fetch Target Account Lists and Groups associated with a Playbook

• Fetch performance data for Playbooks and their campaigns

Note

Currently, the public APIs work best for customers with up to 500 Playbooks and up to 10,000 Accounts targeted per Playbook.

The following is a diagram of the API objects used in managing Playbooks and Target Account Lists. This is an extension of the basic NextRoll object model.

Playbook reporting

You can fetch Playbook reporting data using the GraphQL Reporting API. You’ll want to query for the Campaign node.

A Playbook consists of multiple Universal Campaigns. In the RollWorks dashboard, we show aggregate metrics for a Playbook and metrics for the individual campaigns within the Playbook.

The GraphQL Reporting API doesn’t support querying for a Playbook directly. You’ll first need to query for all campaigns in an Advertisable. Then you’ll aggregate the campaign metrics in your application.

For example, the following query fetches metrics for all campaigns for an Advertisable. You can use the playbookEID node to see which inventory campaigns are associated with a Playbook.

Note

The flags(enableUniversalCampaigns: true) snippet is important when querying metrics, or we’ll return the inventory campaigns within the Universal Campaign rather than aggregate Universal Campaign objects.

query PlaybookCampaignsExample{
  flags(enableUniversalCampaigns: true)
  advertisable {
    byEID(advertisable: "MY_ADVERTISABLE_EID") {
      eid
      name
      campaigns(isActive: true, statuses: ["running"]) {
        eid
        name
        status
        playbookEID
        playbookName
        playbookType
        metrics(start: "2021-08-01", end: "2021-08-30", currency: "USD") {
          summary {
            cost
            impressions
            clicks
          }
        }
      }
    }
  }
}

Retrieve Playbook objects

To manipulate Playbooks, you’ll first need to fetch the list of Playbooks for your Advertisable.

The GET /activate/api/v2/playbooks/simple endpoint can be used to retrieve the list of playbooks for an Advertisable. Only the essential metadata for a Playbook is in the response, such as the name, EID, status, type, and Target Account List.

Once you have the Playbooks for an Advertisable, the most common action is to view and manipulate the Playbook’s Target Account Lists. In the response, you’ll find a tal_eid field. This EID is used to query GET /audience/v1/target_accounts/(tal_eid) to get details for the Target Account List.

For details on working with Target Account lists, see Manage Target Account Lists.