Campaign

1
2
3
4
5
{
    "Name": "Mopedo.Bidding.Campaign",
    "Kind": "EntityResource",
    "Methods": ["GET", "POST", "PATCH", "PUT", "DELETE", "REPORT", "HEAD"]
}

The Campaign resource connects ads in the Ad resource with bid rules that determine under which circumstances a bid containing the ad should be sent as response to a bid request. The campaign also contains a budget and a time frame under which the campaign should be active.

Format

Properties marked in bold are required.

Property name Type Description
Id string A unique id for the campaign
Label string A describing label for the campaign
BuyerId string An optional ID of the buyer of this campaign, for reference in reports etc.
Priority integer Campaigns with higher numbers will be evaluated first
StartDateTime datetime The point in time when the campaign begins
EndDateTime datetime The point in time when the campaign ends
DaysRemaining float (read-only) The number of days remaining until EndDateTime
IsPaused boolean Paused campaigns are skipped during bid request evaluation
SampleImageUrl string A URL to an image, representative of the campaign
AdvertiserDomain string The domain of the advertiser
Budget Budget The budget used to control spending for this campaign
BidRules array of BidRule The rules determining which bid requests to respond to
IsValid boolean (read-only) True if and only if all fields have valid values
Errors array of Error (read-only) The errors of the campaign, or empty if valid
IsActive boolean (read-only) true if valid, not paused, not spent and within its time frame
IsUpcoming boolean (read-only) Current time is before StartDateTime
IsCompleted boolean (read-only) Current time is after EndDateTime
NrOfBids (read-only) integer The total number of bids generated by the campaign
NrOfWins (read-only) integer The total number of wins generated by this campaign
NrOfClicks (read-only) integer The total number of clicks generated by this campaign
AverageBidPrice (read-only) Price The average price for the bids of this campaign
AverageWinPrice (read-only) Price The average prace for the wins of this campaign
WinRate (read-only) float The number of wins divided by the number of bids
ClickRate (read-only) float The number of clicks divided by the number of wins
LatestWinAt datetime (read-only) The date and time of the latest win
Paused boolean Obsolete: Use IsPaused instead

Hidden properties can be included in response bodies by using the add meta-condition in the request URI.

Budget

Budgets contain values describing the financial limitations of the campaign. Campaigns that reach their daily and/or total budgets will no longer be considered in future bid request evaluations (IsActive will be false for those Campaign entities).

Format

Property name Type Description
DailyBudget Price The value spendable within a single day
TotalBudget Price The total value spendable for the campaign
DailySpent Price (read-only) The value spent today
TotalSpent Price (read-only) The value spent this far for the entire campaign
DailyRemaining Price (read-only) The value remaining until the daily budget is spent
TotalRemaining Price (read-only) The value remaining until the total budget is spent

BidRule

BidRule entities are used to define conditions under which a certain Ad is supposed to be returned as response to a bid request, and at what bid price. Each BidRule contains an array of Condition entities, all making certain assertions about the properties of bid requests – for example that the domain of the site where the impression is located is "nytimes.com" or that the device is located in the UK. If and only if all conditions in the bid rule are true for an incoming bid request, the DSP will select the BidTemplate (or pick one at random if there is more than one in the array) from BidTemplates and place bids on all the impressions of the bid request using it. Most bid requests only contain one impression, but this behavior is worth noting.

Format

Property name Type Description
Conditions array of Condition The rule is true for a bid request if all conditions are true for it
BidTemplates array of BidTemplate If the array includes more than one, one will be picked at random

Condition

Each Condition entity encodes a predicate that is either true or false of a given bid request. They are used in bid rules to define the comparison logic used when determining which bid template to use in a bid response. They are defined by a Key, which is a path expression to some property to compare against, an Operator that defines the comparison operation, and a Value that holds the value to compare against. The DSP will automatically type check all conditions with Key path expressions referring to properties of statically typed resources, and their operators, and notify the user if there are any errors, by updating the Errors array in the Campaign entity.

Format

Property name Type Description
Key string The path expression to (including the name of) the property described
Operator enum The operator to use in the comparison
Value dynamic The value asserted for the property, can be of any type

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "Key": "Device.IP",
    "Operator": "EQUALS",
    "Value": "94.254.87.113"
},
{
    "Key": "User.Extension.GroupNr",
    "Operator": "GREATER THAN",
    "Value": 5
}
,
{
    "Key": "Site.AdWinCount(ad01)",
    "Operator": "LESS THAN OR EQUALS",
    "Value": 5
}

BidTemplate

Bid templates define the ads that should be considered if all conditions in the bid rule are true for a given bid request, and the price to use in bids with those ads.

Each BidTemplate can contain many ad ID strings, which is useful when including different formats for a single creative. When evaluating a bid request, the bidder will choose the first Ad that matches the dimensions of the impression up for auction.

Format

Property name Type Description
AdIds array of string The AdIds of the ads connected to this bid template
Price Price The bid price for the bid, will always be converted to CPM

Views

The Campaign resource has one view:

FromIds

FromIds takes a comma-separated list of campaign IDs, and returns their corresponding campaigns. Example URI: /campaign-fromids/campaignIds=c1,c2,c3.

Format

Property name Type Description
CampaignIds string A comma-separated list of campaign IDs

Campaign example

We can upload campaigns by making a POST or PUT request to the Mopedo.Bidding.Campaign resource:

1
2
cd /Users/erik/Desktop
curl -X PUT 'https://my-dsp.com:8282/rest/bidding.campaign/id=c1' -d '@data.json' -H 'Authorization: apikey mykey'

We insert a new campaign with Id equal to "c1", or update any existing Campaign with that Id. As data we use data.json, a text file located on my desktop with the following JSON-formatted content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
    "Id": "c1",
    "Label": "My first campaign",
    "Priority": 4,
    "StartDateTime": "2017-01-20T00:00:00",
    "EndDateTime": "2017-05-20T00:00:00",
    "Paused": false,
    "SampleImageUrl": "http://my-dsp.com/samples/c1.jpg",
    "AdvertiserDomain": "my-dsp.com",
    "Budget": {
        "DailyBudget": {
            "Amount": 350,
            "Currency": "SEK",
            "CPM": false
        },
        "TotalBudget": {
            "Amount": 2000,
            "Currency": "USD",
            "CPM": false
        }
    },
    "BidRules": [{
        "Conditions": [{
            "Key": "Site.Domain",
            "Operator": "CONTAINS",
            "Value": "nytimes.com"
        }, {
            "Key": "User.Extension.Group",
            "Operator": "EQUALS",
            "Value": "A123"
        }],
        "BidTemplates": [{
            "Price": {
                "Amount": 25,
                "Currency": "USD",
                "CPM": true
            },
            "AdIds": ["ad01"]
        }]
    }]
}