This tutorial will walk you through the steps of writing a small python script that can connect to the Platform API, list all Event Triggered campaigns, and then will pause and resume all of them.

Requirements

  1. Python 3 with “requests” and “json” modules installed
  2. An API key with access to one or more game environments. (Note, it is highly recommended you work only in Dev environments whilst learning or experimenting with API keys)

Authenticate

For future examples, we’ll adjust the code above so that the idToken is returned from a method called getToken()

List environments

One of the first things we’ll want to do is find the environment ID of the game environment we want to influence campaigns for. The following python script, combined with the code that gets a token above, will get us an array of objects, each with IDs and names for the games in question.

I’m particularly interested in the Live environment for DeltaSlot, as I already know that this environment has Event Triggered campaigns.

using the code above, I’ve found the environment ID to be 8756.
This is going to be important for any operations that are specific to a given environment.

List campaigns

It’s important to remember that deltaDNA offers two different types of campaigns, Event Triggered and Decision Point campaigns. This example will use Event Triggered campaigns and the endpoints:
/api-docs/engage/v1/campaigns/event-triggered for listing all campaigns, and /api-docs/engage/v1/campaigns/event-triggered/{id} for getting details on a specific campaign.

I’ve tweaked the code from the last example to add some basic error handling for invalid responses.

With the above code, I get the following JSON which corresponds to the all the campaigns the key has access to, without any inherent filtering based on game. For simplicity, these have been truncated to those in the game DeltaSlot, environment ID 8756.

You might find that if your keys have access to multiple games with lots of campaigns, that this can be quite a significant amount of data to transfer from our API. To help with that we have the next section of this tutorial

Pagination

We can provide parameters to split the returned results from all of our ‘list’ queries into chunks. We can supply two parameters which will determine the number of entries returned in a single request (the size of each page), and the number of which page the user

key value
‘limit’ the number of entries per response
‘page’ starting point for the query.

With a limit of 3, and page being 0 or omitted, we will only get the first 3 campaigns.
After setting the page to 1, we will then get campaigns 4-6, and so on.

Controling campaigns

Now we’ve got a list of campaign IDs, we can create a more complex request. The ones we’re going to be using are /api/engage/v1/campaigns/event-triggered/{id}/pause and /api/engage/v1/campaigns/event-triggered/{id}/play

Pausing campaigns

Before we pause a campaign, we need to have the IDs available. From our listing process above, it’s very easy to get a list of all campaigns.
The following code takes a response object and turns it into an array of integers, which is what will be used for examples below

The endpoint we’re using is different in structure to the previous.

  • This one has no parameters
  • This one has no body
  • The target ID is conveyed in the URL itself

To create the URL that includes the target ID, I use a formatted Python string to replace the placeholder with the variable “ID”.

The full code to pause all campaigns, including feedback handling from the platform, looks like the following:

in my example environment, it produces the following:

Resuming Campaigns

The same code as pausing can be used, except the “play” endpoint instead.

which results in:

Bad Requests & Invalid operations

In the examples above, efforts to pause the campaign “34751” failed, as the campaign is not yet finalised.
This is reflected in the Platform User Interface:
enter image description here

At a glance we can see that the one of the three campaigns hasn’t been started yet, and therefore pausing and unpausing aren’t valid operations that can be applied to the campaign.

As a troubleshooting rule – if the platform is unable to give you a meaningful text message response, then check the following common pitfalls.

A response code of 5xx (500 or above) means something on our end has gone wrong. Contacting support with the request you made may enable us to identify the cause, or harden the platform API to be more resilient to unusual requests.

A response code of 4xx (400 or above) means something with your client application isn’t working correctly. Examples include

  • an invalid / incorrect target URL
  • bad input (like malformed JSON)
  • an expired to token
  • trying to perform actions the key does not have permissions to do.