Goal rules v2 requests

Note:

The recommended combination of goal and goal rules endpoints, which provides the most complete support for all goal settings and goal targeting rules, is: Goal 1.0.cpvext endpoints for manipulating your goals and Goal rules v2 endpoints for manipulating goal targeting rules.

  • Goal 1.0.cpvext endpoints have support for all goal types, pricing models, impression and event caps, and mid-roll break targeting, which is not supported through Goal 1.0 endpoints. You should migrate to Goal 1.0.cpvext endpoints if you are still using Goal 1.0 endpoints for manipulating your goals.
  • Goal rules v2 endpoints support getting and updating all targeting rules for all goal types. You should migrate to Goal rules v2 endpoints if you are still using one of the below:
    • Goal rules 1.0 endpoints, which only support getting and updating targeting rules for share of voice, impression, priority unreserved (RTB), and unlimited impression goals, and have no support for audience targeting, browser/OS targeting, and IP targeting
    • Goal rules 1.0.cpvext endpoints, which do not have support for audience targeting, browser/OS targeting, and IP targeting.

This endpoint complements the Goal API but it uses a different base URL and communication format. The endpoints described below support getting and updating all targeting rules for all goal types.

Getting started

  • Base URL: https://api.videoplaza.com/api/v2/goal
  • Requests: GET and PUT requests are used. You pass parameters by using common REST parameters like PATH and QUERY, as well as HTTP HEADERS. The body of the requests should be provided in JSON format and encoded using UTF-8.
  • Responses: All responses contain an HTTP status code in the header and the body is in JSON format.
  • Related user documentation: Targeting rules
The goal rules v2 endpoints allow you to:

Request body format

To update goal rules, you need to supply a body to the request with the following format:

{
    "parentId": "<goal ID>",
    "frequencyRules": [FrequencyRuleBean],
    "locationRules": [LocationRuleBean],
    "timeRules": [TimeRuleBean],
    "tagAndPartnerRules": [TagRuleBean or ContentPartnerRuleBean],
    "categoryRules": [CategoryRuleBean],
    "ipRules": [IpRuleBean],
    "userAgentRules": [UserAgentRuleBean],
    "ignoreParentLocationRules": <boolean>,
    "ignoreParentTagRules":  <boolean>,
    "ignoreParentContentRules":  <boolean>,
    "ignoreParentTimeRules":  <boolean>,
    "ignoreParentFrequencyRules":  <boolean>,
    "ignoreParentIpRules":  <boolean>,
    "ignoreParentUserAgentRules":  <boolean>,
    "audienceTargeting": {    (Required only if you have an audience data integration added for your account)
      "<audience data provider ID>": {
        "ignoreParent": <boolean>,
        "rules": [AudienceSegmentRuleBean]
        }
    },
    "accountCustomParameterRules": [    (Required only if you have account custom parameters enabled and configured for your account)
       {
         "ignoreParent": <boolean>,
         "parameterName": "acp.paramName",  (paramName needs to match the ad request parameter name defined for your Pulse account)
         "rules": [AccountCustomParameterRuleBean]
         ]
       }
    ]
}
  • FrequencyRuleBean
    {
    "impressions": <number of impressions to allow in this time period>,
    "timeUnit": "FIVE_MINUTES" |"TEN_MINUTES" |"QUARTER_HOUR" | "HALF_HOUR" | "HOUR" | "DAY" | "WEEK" | "MONTH" | "GOAL_LIFETIME"
    }
  • LocationRuleBean
     {
     "locationId": "<location ID>",
     "locationType": "CITY" | "REGION" | "COUNTRY" | "METRO",
     "locationName": "Germany" | "Berlin",    (Setting this value is ignored)
     "access": "ALLOW" | "DENY"
      }
  • TimeRuleBean

    Time rules should be set based on the account's time zone.

    {
     "active": true | false,
     "days": [ "MONDAY" | "TUESDAY" | "WEDNESDAY" | "THURSDAY" | "FRIDAY" | "SATURDAY" | "SUNDAY" ],
     "fromHour": 0 - 23,
     "fromMinute": 0 - 59,
     "toHour": 0 - 23,
     "toMinute": 0 - 59
      }

    If you set a specific time rule combination to active, then the rest is considered inactive. You can have both active and inactive rules if you want to set a portion of the active period to be inactive. For example, active on Saturday between 08:00 a.m. and 11:00 a.m., but inactive for 15 minutes on Saturday, between 10:00 a.m. and 10:15 a.m.

    Time rule set to, for example, "toHour": 5 and "toMinute": 59 actually means it is set to 05:58:59 (hour 5, minute 58, second 59). To capture the last minute of the hour in this example, you need to set the time rule "toHour": 6 and "toMinute": 0.

    To extend a rule to the next day, use "toHour": 0 and "toMinute": 0.

  • TagRuleBean
    {
     "tag": "<tag  value>",
     "resourceType": "TAG",
     "ruleType": "ALL_OF" | "AT_LEAST_ONE_OF" | "NONE_OF"
      }
    Note: When setting the tag rule to AT_LEAST_ONE_OF, you need to provide at least two tags using separate TagRuleBean.
  • ContentPartnerRuleBean
    {
     "partnerId": "<content partner ID>",
     "partnerName": "<content partner name>",  (Setting this value is ignored)
     "resourceType": "CONTENT_PARTNER",
     "ruleType": "ALL_OF" | "AT_LEAST_ONE_OF" | "NONE_OF"
      }
  • CategoryRuleBean
    {
     "categoryId": "<category ID>",
     "categoryName": "<category name>",  (Setting this value is ignored)
     "ruleType": "AT_LEAST_ONE_OF" | "NONE_OF"  ("ALL_OF" is not allowed for categories)
      }
  • IpRuleBean
    {
     "ipMatcher": "192.168.0.1" | "192.168.0.1-68" | "192.168.0.*",
     "access": "ALLOW" | "DENY"
      }
  • UserAgentRuleBean
    {
     "browsers": [ "IE" | "FIREFOX" | "CHROME" | "SAFARI" | "OPERA" | "OTHER" ],
     "operatingSystems": [ "WINDOWS" | "MACOSX" | "LINUX" | "IOS" | "ANDROID" | "OTHER" ],
     "access": "ALLOW" | "DENY"
      }
  • AudienceSegmentRuleBean
    Note: You can leave this part out if you are not using the Pulse Audience Management functionality and you do not have an audience data provider integration added for your account.
    {
     "segmentId": "<audience data provider ID>[<segmentationId>]=<segmentId>",
     "segmentName": "<segmentationName>:<segmentName>",  (Setting this value is ignored)
     "ruleType": "ALL_OF" | "AT_LEAST_ONE_OF" | "NONE_OF"
      }

    The information for accurately constructing the AudienceSegmentRuleBean can be found through the Audience Management API.

    Note: If you have provided us with a Segment Identification Document when integrating, you may notice that the naming differs from the one used in the Audience Management API. See Data integration structure for more details on the different parameters, and their old and new naming.
  • AccountCustomParameterRuleBean
    Note: You can leave this part out if you are not using the Account Custom Parameter functionality and you do not have any account custom parameters defined for your account.
    {
      "value": "<string>",  (Value for the corresponding acp parameter defined for your Pulse account)
      "ruleType": "AT_LEAST_ONE_OF" | "NONE_OF" ("ALL_OF" is not allowed for account custom parameters)
    }
    Note:
    • You can add a maximum of 20 values for one account custom paramater.
    • The account custom parameter values cannot contain any spaces or any of the following characters: comma (,), semicolon (;), double quote/quotation mark ("), single quote/apostrophe ('), backslash (\), pipe (|), tilde (~), or ampersand (&).
  • The ignoreParentRules parameters can be set to:
    • true: If you want to partially or completely change the targeting for a goal, you need to ignore the corresponding parent (campaign) rule that does not match the new targeting. A configured (not empty) parent rule has to be ignored when it partially or entirely conflicts with the desired targeting outcome.
    • false:
      • When the parent (campaign) rule is empty (not configured). If a campaign targeting rule is empty, Pulse treats it as a matching rule, because an empty rule matches all requests.
      • When the child (goal) rule is exactly the same as the parent (campaign) rule or is a subset of the parent (campaign) rule.

      For more information, see Apply and ignore targeting rules.

v2 Update goal rules

Method PUT
URL https://api.videoplaza.com/api/v2/goal/{id}/rules
Header Authentication header (x-o-api-key)
Content type application/json
URL params ID of the goal
Query params -
Body Request body format
Success response

HTTP status: 204 No Content

Header: -

Body: -

Example

Request header

PUT /api/v2/goal/f728064b-803f-4a82-a5d7-9efab5d4538a/rules HTTP/1.1
Host: api.videoplaza.com
Content-­type: application/json
x-o-api-key="<your key>"

Request body

{
    "parentId": "f728064b-803f-4a82-a5d7-9efab5d4538a",
    "frequencyRules": [
        {
            "impressions": 20,
            "timeUnit": "GOAL_LIFETIME"
        },
        {
            "impressions": 2,
            "timeUnit": "HALF_HOUR"
        },
        {
            "impressions": 1,
            "timeUnit": "QUARTER_HOUR"
        }
    ],
    "locationRules": [
        {
            "locationId": "34785",
            "locationType": "CITY",
            "locationName": "mumbai",
            "access": "ALLOW"
        },
        {
            "locationId": "356",
            "locationType": "COUNTRY",
            "locationName": "india",
            "access": "ALLOW"
        },
        {
            "locationId": "356002",
            "locationType": "METRO",
            "locationName": "mumbai metropolitan region",
            "access": "ALLOW"
        },
        {
            "locationId": "297",
            "locationType": "REGION",
            "locationName": "india",
            "access": "ALLOW"
        },
        {
            "locationId": "643",
            "locationType": "COUNTRY",
            "locationName": "russian federation",
            "access": "DENY"
        }
    ],
    "timeRules": [
        {
            "active": true,
            "days": [
                "SUNDAY",
                "SATURDAY"
            ],
            "fromHour": 0,
            "fromMinute": 0,
            "toHour": 23,
            "toMinute": 59
        }
    ],
    "tagAndPartnerRules": [
        {
            "resourceType": "TAG",
            "ruleType": "ALL_OF",
            "tag": "sport"
        },
        {
            "resourceType": "TAG",
            "ruleType": "AT_LEAST_ONE_OF",
            "tag": "basketball"
        },
        {
            "resourceType": "TAG",
            "ruleType": "AT_LEAST_ONE_OF",
            "tag": "football"
        },
        {
            "resourceType": "TAG",
            "ruleType": "NONE_OF",
            "tag": "golf"
        }
    ],
    "categoryRules": [
        {
            "categoryId": "df5480fd-ca38-43c8-a44c-4240965e2023",
            "categoryName": "Sport",
            "ruleType": "AT_LEAST_ONE_OF"
        },
        {
            "categoryId": "0d828b6b-5753-47a9-9a72-8639765193b3",
            "categoryName": "News",
            "ruleType": "NONE_OF"
        }
    ],
    "ipRules": [
        {
            "ipMatcher": "192.168.0.2",
            "access": "DENY"
        },
        {
            "ipMatcher": "192.168.0.1",
            "access": "ALLOW"
        }
    ],
    "userAgentRules": [
        {
            "access": "DENY",
            "browsers": [
                "IE",
                "SAFARI",
                "OPERA"
            ],
            "operatingSystems": [
                "LINUX"
            ]
        },
        {
            "access": "ALLOW",
            "browsers": [
                "FIREFOX",
                "CHROME"
            ],
            "operatingSystems": [
                "WINDOWS",
                "MACOSX"
            ]
        }
    ],
    "ignoreParentLocationRules": true,
    "ignoreParentTagRules": true,
    "ignoreParentContentRules": true,
    "ignoreParentTimeRules": true,
    "ignoreParentFrequencyRules": true,
    "ignoreParentIpRules": true,
    "ignoreParentUserAgentRules": true,
    "accountCustomParameterRules": [
        {
            "ignoreParent": true,
            "parameterName": "acp.genre",
            "rules": [
                {
                    "value": "Comedy",
                    "ruleType": "AT_LEAST_ONE_OF"
                }
            ]
        },
        {
            "ignoreParent": false,
            "parameterName": "acp.network",
            "rules": [
                {
                    "value": "Network1",
                    "ruleType": "AT_LEAST_ONE_OF"
                }
            ]
        }
    ],
    "audienceTargeting": {
        "7915b4ad-0572-4d88-bcf9-7f0813c953b3": {
            "ignoreParent": true,
            "rules": [
                {
                    "segmentId": "7915b4ad-0572-4d88-bcf9-7f0813c953b3[0]=2",
                    "segmentName": "Gender:Female",
                    "ruleType": "ALL_OF"
                },
                {
                    "segmentId": "7915b4ad-0572-4d88-bcf9-7f0813c953b3[1]=2",
                    "segmentName": "Age:16-21",
                    "ruleType": "AT_LEAST_ONE_OF"
                },
                {
                    "segmentId": "7915b4ad-0572-4d88-bcf9-7f0813c953b3[1]=3",
                    "segmentName": "Age:21-29",
                    "ruleType": "AT_LEAST_ONE_OF"
                }
            ]
        }
    }
}

Success response

HTTP status:
  204 (No Content)

v2 List goal rules by goal ID

Method GET
URL https://api.videoplaza.com/api/v2/goal/{id}/rules
Header Authentication header (x-o-api-key)
Content type application/json
URL params ID of the goal
Query params -
Body -
Success response

HTTP status: 200 OK

Header: -

Body: list of rules

Example

Request header

GET /api/v2/goal/f728064b-803f-4a82-a5d7-9efab5d4538a/rules HTTP/1.1
Host: api.videoplaza.com
Content-type: application/json
x-o-api-key="<your key>"

Request body: NA

Success response

HTTP status:
    200 (OK)
 
Body:
{
    "parentId": "f728064b-803f-4a82-a5d7-9efab5d4538a",
    "frequencyRules": [
        {
            "impressions": 2,
            "timeUnit": "HALF_HOUR"
        }
    ],
    "locationRules": [
        {
            "locationId": "34785",
            "locationType": "CITY",
            "locationName": "mumbai",
            "access": "ALLOW"
        },
        {
            "locationId": "356",
            "locationType": "COUNTRY",
            "locationName": "india",
            "access": "ALLOW"
        },
        {
            "locationId": "297",
            "locationType": "REGION",
            "locationName": "india (?)",
            "access": "ALLOW"
        },
        {
            "locationId": "356002",
            "locationType": "METRO",
            "locationName": "mumbai metropolitan region",
            "access": "DENY"
        }
    ],
    "timeRules": [
        {
            "active": true,
            "days": [
                "SUNDAY",
                "SATURDAY"
            ],
            "fromHour": 0,
            "fromMinute": 0,
            "toHour": 23,
            "toMinute": 59
        }
    ],
    "tagAndPartnerRules": [
        {
            "resourceType": "TAG",
            "ruleType": "ALL_OF",
            "tag": "sport"
        },
        {
            "resourceType": "TAG",
            "ruleType": "AT_LEAST_ONE_OF",
            "tag": "basketball"
        },
        {
            "resourceType": "TAG",
            "ruleType": "AT_LEAST_ONE_OF",
            "tag": "football"
        },
        {
            "resourceType": "TAG",
            "ruleType": "NONE_OF",
            "tag": "hockey"
        }
    ],
    "categoryRules": [
        {
            "categoryId": "df5480fd-ca38-43c8-a44c-4240965e2023",
            "categoryName": "Sport",
            "ruleType": "AT_LEAST_ONE_OF"
        }
    ],
    "ipRules": [
        {
            "ipMatcher": "192.168.0.2",
            "access": "DENY"
        }
    ],
    "userAgentRules": [
        {
            "access": "ALLOW",
            "browsers": [
                "FIREFOX",
                "CHROME"
            ],
            "operatingSystems": [
                "WINDOWS",
                "MACOSX"
            ]
        }
    ],
    "audienceTargeting": {
        "7915b4ad-0572-4d88-bcf9-7f0813c953b3": {
            "ignoreParent": false,
            "rules": [
                {
                    "segmentId": "7915b4ad-0572-4d88-bcf9-7f0813c953b3[0]=2",
                    "segmentName": "Gender:Female",
                    "ruleType": "ALL_OF"
                },
                {
                    "segmentId": "7915b4ad-0572-4d88-bcf9-7f0813c953b3[1]=2",
                    "segmentName": "Age:16-21",
                    "ruleType": "ALL_OF"
                }
            ]
        }
    },
    "accountCustomParameterRules": [
        {
            "ignoreParent": false,
            "parameterName": "acp.genre",
            "rules": [
                {
                    "value": "Comedy",
                    "ruleType": "AT_LEAST_ONE_OF"
                }
            ]
        },
        {
            "ignoreParent": false,
            "parameterName": "acp.network",
            "rules": [
                {
                    "value": "Network1",
                    "ruleType": "AT_LEAST_ONE_OF"
                }
            ]
        }
    ],
    "ignoreParentLocationRules": false,
    "ignoreParentTagRules": false,
    "ignoreParentContentRules": false,
    "ignoreParentTimeRules": false,
    "ignoreParentFrequencyRules": false,
    "ignoreParentIpRules": false,
    "ignoreParentUserAgentRules": false
}