Traffic routing

A branded short link can route/redirect all the incoming redirection requests to the destination URL you defined by the time you had created it.

Although you can edit a link's destination URL anytime after creation, there are use-cases where you need the same single short link to redirect different requests to different destination URLs when a specific condition holds.

For instance, you might need a short link to redirect to a different web content according to the Country where the request originated from, or you might decide which is the best possible next destination URL to provide according to a device's preferred language of choice.
Conditional routing by [Origin] Country and by [Device] Language are both examples of link options you can define for a given branded link.

📘

Traffic routing feature

Traffic routing is paid feature and may not be available with all subscriptions.

In the Rebrandly API, you can define a set of destination URLs where the link could possibly redirect to, and associate a triggering rule to each of them, so that when the incoming traffic matches the conditions your rule defines, the corresponding URL is selected and used for the redirection.

Conditional Routing model

Example of conditional routing by Country for a link are:

• redirect the link to https://edition.cnn.com/uk whenever the traffic is found to be originating from the UK
• otherwise, redirect the link to https://edition.cnn.com/australia whenever the detected country of origin is Australia, instead
• in all other cases, i.e. when detected origin is neither in the UK nor in Australia mainland, redirect the link to https://edition.cnn.com/world

In the first rule above, the condition can be seen as the traffic originated from the UK, whereas the destination URL of choice associated would be https://edition.cnn.com/uk.
A condition can also bring a higher level of complexity, e.g. the traffic originated from the UK and the device's default language set is the English. The conjunction operator "and", in this sentence, would serve as a way to express the need to have both of the conditions traffic originated from the UK and device language is English to be matched in order for the destination URL of this rule to be selected.

Evaluation strategy

Rules are evaluated in the chronological order they have been associated to the link, so that if the condition defined for a URL is not verified, the next rule in the sequence will be evaluated, until a rule's condition is eventually matched, or there are no more rules to evaluate (in which case, the default destination URL of the link will be used).

Mind that, in case a property's value is not available in the event of a click on a link, every rule relying on such property will not be evaluated.

[
  {
    "id": "14e56f7df1d642d7b3d447e3491a5780",
    "destination": "https://edition.cnn.com/uk",
    "condition": {
      "property": "req.country",
      "operator": "in",
      "values": ["uk"]
    }
  },
  {
    "id": "d97e0d9078794f5993943db08cc956a5",
    "destination": "https://edition.cnn.com/australia",
    "condition": {
      "property": "req.country",
      "operator": "in",
      "values": ["au"]
    }
  }
]

Limits and defaulting/fallback

You can associate up to 10 routing rules to any given link and define a different destination URL for each rule. If any of the routing rules you’ve created for a link do not apply (e.g. if you only have a rule pertaining to traffic originating from the United States, and you get traffic from Spain), anyone who falls outside of the rule-based routing will be directed to the original destination URL by default.

Condition format

A condition is defined as a tuple of information:

• which property should be observed to decide where to go next in the routing process. Example properties are req.country, req.language, etc.
• which logical operator, if suitable for the specific property, will be used to decide whether this condition holds or not according to the scenario found on the traffic in realtime. Example operators are in (inside, or one of), gt (greater than), etc.
• which set of values is relevant for this rule to apply, according to the given property and the operator used to evaluate the condition. An example value is the two-letter ISO country code es (Spain).

Conditions are represented using a JSON object, as in the following example - which represents the condition traffic is originated either from the UK, or from Italy, or from Spain.

Conditions are recursively defined as follows:

A condition can be:
* an AND of two or more conditions
* an OR of two or more conditions
* a tuple `<property, operator, value(s)>`

// a simple condition
{
      "property": "req.country",
      "operator": "in",
      "values": ["uk", "it", "es"]
}

// a condition with an AND operator
// to represent "is from the UK and is an English speaker"
{
  "and": [
    {
      "property": "req.country",
      "operator": "eq",
      "value": "uk"
    },
    {
      "property": "client.language",
      "operator": "eq",
      "value": "en"
    }
  ]
}

// a nested condition with an AND and a OR operator
// to represent "is from UK and is either using Windows as OS or is using Microsoft Edge or Internet Explorer as browser"
{
  "and": [
    {
      "or": [
        {
          "property": "agent.os",
      		"operator": "eq",
      		"value": "windows"
				},
        {
          "property": "agent.browser",
      		"operator": "in",
      		"values": ["microsoft-edge", "ie"]
				}
      ]
    },
    {
      "property": "req.country",
      "operator": "eq",
      "value": "uk"
    }
  ]
}

Conditions themselves do not include any information about the URL which is going to be selected if they happen to be evaluated and to match. The [routing] rule element, instead, is composed up of a condition and a corresponding URL to select in case the condition is matched.

Properties, Operators, Values

The following tables sum up all the possible properties you can use via API, as well as which operators pairs with each property, and which values can be used with the specific operator.

$ curl 'https://api.rebrandly.com/v1/links/FFfa4cc5b6ee45d6g7897b06ac2d16af/rules' \
-X POST \
-H 'apikey: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d \
'{
    "destination": "https://edition.cnn.com/uk",
    "condition": {
      "property": "req.country",
      "operator": "in",
      "values": ["uk"]
    }
 }'

HTTP/1.1 200 OK

$ curl 'https://api.rebrandly.com/v1/links/FFfa4cc5b6ee45d6g7897b06ac2d16af/rules' \
-X GET \
-H 'apikey: YOUR_API_KEY' \
-H 'Content-Type: application/json' \

HTTP/1.1 200 OK

[
  {
    "id": "d97e0d9078794f5993943db08cc956a5",
      "destination": "https://edition.cnn.com/uk",
      "condition": {
        "property": "req.country",
        "operator": "in",
        "values": ["uk"]
      }
   }
]