Goal Rules v2 Requests

Note: This endpoint complements the Goal API but it uses a different base URL and communication format. 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/f28fb170-7db4-4e74-8efb-7541fa2c5004/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": "f28fb170-7db4-4e74-8efb-7541fa2c5004",
 "frequencyRules": [
             {
        "impressions": 2,
        "timeUnit": "HALF_HOUR"
       }
    ],
 "locationRules": [
            {
        "locationId": "10357",
        "locationType": "CITY",
        "locationName": "moscow",
        "access": "DENY"
       },
            {
        "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"
       }
    ],
 "categoryRules": [
            {
        "categoryId": "af574080-133e-4e8c-a3ba-0b212058fb5a",
        "categoryName": "Sport",
        "ruleType": "AT_LEAST_ONE_OF"
       }
    ],
 "ipRules": [
         {
        "ipMatcher": "192.168.0.2",
        "access": "DENY"
       }
    ],
 "userAgentRules": [
         {
        "access": "ALLOW",
        "browsers": [
            "FIREFOX",
            "CHROME"
           ],
        "operatingSystems": [
            "WINDOWS",
            "MACOSX"
           ]
        }
   ],
 "ignoreParentLocationRules": false,
 "ignoreParentTagRules": false,
 "ignoreParentContentRules": false,
 "ignoreParentTimeRules": false,
 "ignoreParentFrequencyRules": false,
 "ignoreParentIpRules": false,
 "ignoreParentUserAgentRules": false,
 "audienceTargeting": {
     "4b621d55-219e-414b-abd4-045b23f69fa8": {
         "ignoreParent": false,
         "rules": [
              {
             "segmentId": "4b621d55-219e-414b-abd4-045b23f69fa8[0]=2",
             "segmentName": "Gender:Female",
             "ruleType": "ALL_OF"
            },
              {
             "segmentId": "4b621d55-219e-414b-abd4-045b23f69fa8[1]=2",
             "segmentName": "Age:16-21",
             "ruleType": "ALL_OF"
            }
         ]
      }
   }
}

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]
  }
 }
}
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": {
 "<audience data provider id>": {
  "ignoreParent": <boolean>,
 "rules": [ AudienceSegmentRuleBean ] (Required only if you have an audience data integration added for your account)
  }
 }
}
  • 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" ,
    "locationName": "Germany" | "Berlin" | ... ,    (Setting this value is ignored)
    "access": "ALLOW" | "DENY"
    }
  • TimeRuleBean
    {
     "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"
    }
  • UserAgentBean
    {
    "browsers": [ "IE" | "FIREFOX" | "CHROME" | "SAFARI" | "OPERA" | "OTHER" , ... ],
    "operatingSystems": [ "WINDOWS" | "MACOSX" | "LINUX" | "IOS" | "ANDROID" | "OTHER" , ... ],
    "access": "ALLOW" | "DENY"
    }
  • AudienceSegmetnRuleBean
    Note: You can leave this part out if you are not using the Ooyala Pulse Audience Management functionality and you do not have an audience data integration added for your account.
    {
    "segmentId": "<audience segment ID>[<index>]<value>",
    "segmentName": "<audience segment name>:<value name>",    (Setting this value is ignored)
    "ruleType": "ALL_OF" | "AT_LEAST_ONE_OF" | "NONE_OF"
    }

Example:

Request header:

PUT /api/v2/goal/f28fb170-7db4-4e74-8efb-7541fa2c5004/rules HTTP/1.1
Host: api.videoplaza.com
Content-­type: application/json
x-o-api-key="<your key>"

Request body:

{
    "parentId": "f28fb170-7db4-4e74-8efb-7541fa2c5004",
    "frequencyRules": [{
        "impressions": 20,
        "timeUnit": "GOAL_LIFETIME"
    }, {
        "impressions": 2,
        "timeUnit": "HALF_HOUR"
    }, {
        "impressions": 1,
        "timeUnit": "QUARTER_HOUR"
    }],
    "locationRules": [{
        "locationId": "4276",
        "locationType": "CITY",
        "locationName": "stockholm",
        "access": "ALLOW"
    }, {
        "locationId": "752",
        "locationType": "COUNTRY",
        "locationName": "sweden",
        "access": "ALLOW"
    }, {
        "locationId": "11358",
        "locationType": "REGION",
        "locationName": "stockholms lan",
        "access": "ALLOW"
    }, {
        "locationId": "10357",
        "locationType": "CITY",
        "locationName": "moscow",
        "access": "DENY"
    }, {
        "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": "92.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,
    "audienceTargeting": {
        "4b621d55-219e-414b-abd4-045b23f69fa8": {
            "ignoreParent": true,
            "rules": [{
                "segmentId": "4b621d55-219e-414b-abd4-045b23f69fa8[0]=2",
                "segmentName": "Gender:Female",
                "ruleType": "ALL_OF"
            }, {
                "segmentId": "4b621d55-219e-414b-abd4-045b23f69fa8[1]=2",
                "segmentName": "Age:16-21",
                "ruleType": "AT_LEAST_ONE_OF"
            }, {
                "segmentId": "4b621d55-219e-414b-abd4-045b23f69fa8[1]=3",
                "segmentName": "Age:21-29",
                "ruleType": "AT_LEAST_ONE_OF"
            }]
        }
    }
}

Success response:

HTTP status:
  204 (No Content)

Was this article helpful?