Targeting Rules API

The Conductrics service includes a Targeting Rules feature, which you can use to define targeting segments and features based on geo-location, time of day, domain names, and other information.

These rules are usually set up using our web-based admin pages. But if you want to create or manage rules programatically, you can do so using the API described here.

Providing Your API Key: You must provide a valid API key to any of the methods in our Targeting Rules API. You can provide it as a URL param called 'apikey' as shown above, or you can pass it in a HTTP Header called 'x-mpath-apikey' if you want to keep it out of the query string.

Contents:

Getting a List of Targeting Rules

You can get a list of current targeting rules via a GET to your 'transforms-list' URL, like so:

GET http://api.conductrics.com/undefined/transforms-list

Assuming your API key has the appropriate access, the server will respond with a JSON data structure like this (comments and newlines added for clarity):

{
  "data": {
    "transforms": [

      // One block like this for each existing transform rule
      {
        "code": "target-gothamites",
        "status": 1 // 1 means enabled, 0 means disabled
        "agents": ["*"], // agent codes(s) rule applies to, or "*" for all agents
        "when": [
          // One item like this for each condition
          // (each item is always a three-element array of strings at this time)
          // if there are no conditions for this rule, just provide an empty array
          [
            "geoCity", // should be one of the recognized source data types
            "eq", // comparison operator
            "New York" // value to compare to
          ],
          ...
        ],
        // Optional "and" vs "or" evaluation, can be "and" (the default) or "or"
        // (makes no difference unless more than one condition in "when" array)
        "andor": "and", 
        // Targeting to apply when the rule "fires" (all conditions are met)
        "apply": {
           // Tag with a targeting feature(s) - use commas for multiple features
          "feature": "gothamite" // prefix with # for a Conductrics-provided feature
          // Can also assign segment, but in practice likely just one or the other
          "segment": "urbanites" // Change the targeting segment
        }
      },
      ...
    ]
  }
}

Deleting a Targeting Rule

You can delete a targeting rule by issuing a DELETE to the targeting rule's base URL, like so:

DELETE http://api.conductrics.com/undefined/transform-rule/my-rule

Assuming your API key has the appropriate access, the server will respond with a simple status message:

{
  "success": true
}

This API call corresponds to the 'Delete Targeting Rule' button in our web-based tools.

Creating or Changing a Targeting Rule

You can create a new targeting rule (or make changes to an existing one) by issuing a PUT to the desired rule's base URL, with the desired rule JSON sent as the message body.

PUT http://api.conductrics.com/undefined/transform-rule

The body of the request should be the JSON description of the desired targeting rule, with whatever conditions you want in the 'when' part and the feature or segment to apply in the 'apply' part. See the preceding section for examples of what the JSON document should look like.

Assuming your API key has the appropriate access, the server will respond with a simple status message:

{
  "success": true
}

Example: Creating a Rule for Automatic Targeting Features

Let's assume a scenario where:

  • The user has a way to check off one or more 'Automatic Targeting' features, by providing a checkbox for each automatic targeting feature 'source'. You could populate such a UI dynamically by getting the list of targeting options and presenting a checkbox for each item in the providers array that has the providesFeatures:true flag.

  • You want the rule to apply to my-agent-1 (which may or may not exist yet)

  • You don't want to provide any 'conditions' for the rule - it should always apply the selected automatic targeting features

In such a scenario, you would create the rule by sending the following to Conductrics via a PUT operation (see above).

{
	"code": "my-targeting-rule",
	"status": 1,
	"agents": ["my-agent-1"],
	"when": [],
	"apply": {
		"feature": "#geoContinent,#uaIsMobile"
	}
}

Getting a List of Available Source Data Options

You can get a list of available 'source data' types for targeting rule conditions by issuing a GET to your 'transforms-options' URL.

You could use this to create a UI for creating rules within your own app, if you just need programatic access to the list for any other reason.

PUT http://api.conductrics.com/undefined/transforms-options

Assuming your API key has the appropriate access, the server will respond with a JSON structure like the following:

{
  "data": {
    "options": {
      // List of known source data "providers" for targeting rule conditions
      "providers": [
        // one item like this for each supported rule
        {
          "level": 2 // Level 2 providers are best as automatic targeting features
          "code": "reoRegionWorld", // source data type (can use in 'when' conditions)
          "name":"Region of World", // friendly name
          "help": "A region of the world...", // descriptive help text
          "examples": ["Northern-America","Southern-Europe"], // a few sample values
          "tags": ["Geo"] // simple categories ('hints' about usage)
          "providesFeatures":true // true if source provides 'automatic targeting features'
        },
        // ...more source data providers...
      ]
      // List of available "operators"
      "operators": [
        {"code": "eq", "name":"is"},
        {"code": "neq", "name":"is not"},
        // ...other operators...
      ]
    }
  }
}