Goal Rules v2 Requests

This endpoint complements the Goal API but it uses a different base URL and communication format. Audience targeting, browser/OS targeting, IP targeting, as well as capping the maximum number of impressions per 15 minutes, 30 minutes, and goal lifetime is only supported through this endpoint.

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 endpoint allows you to:

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
}

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
{
    "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": {
       "<audience data provider ID>": {
          "ignoreParent": <boolean>,
          "rules": [AudienceSegmentRuleBean]
       }
    },
    "accountCustomParameterRules": [
        {
          "ignoreParent": <boolean>,
          "parameterName": "acp.paramName",
          "rules": [AccountCustomParameterRuleBean]
         ]
       }
    ]
}
Success response

HTTP status: 204 No Content

Header: -

Body: -

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": "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 specified 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
      }
  • 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.

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": false,
            "days": [
                "MONDAY",
                "TUESDAY",
                "WEDNESDAY",
                "THURSDAY",
                "FRIDAY"
            ],
            "fromHour": 0,
            "fromMinute": 0,
            "toHour": 23,
            "toMinute": 59
        },
        {
            "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)