Rules

Rules are a fundamental part of our system, allowing you to define conditions under which specific behaviors are executed. This documentation will explain how rules work, the order in which they are executed, and provide detailed descriptions of all rule types and behaviors.

How Rules Work

Rules are evaluated in the order they are defined. When a request is made, the system checks each rule sequentially until it finds a match. Once a rule matches, the corresponding behavior is executed. If no rules match, a default behavior is applied.

Rule Types

• Basic Rule: The Basic Rule always matches and is typically used as a fallback when no other rules match.

• Country Rule: The Country Rule matches based on the user’s country. It uses the ISO 3166-1 alpha-2 country codes.

• Device Rule: The Device Rule matches based on various characteristics of the user’s device, such as:

  • Bot Control: Whether the rule should include, exclude or exclusively match bots.
  • Device Type: The type of device (e.g., mobile, tablet).
  • Browser: The browser being used.
  • Browser Version: The version of the browser.
  • CPU: The CPU of the device.
  • Vendor: The vendor of the device.
  • Model: The model of the device.
  • Operating System: The operating system of the device.
  • Operating System Version: The version of the operating system.
  • Engine: The rendering engine of the browser.
  • Engine Version: The version of the rendering engine.

• Time Rule: The Time Rule matches based on the current time. It can be configured to match before or after a specific time. Useful for enabling or expiring a behavior after a specific time.

• Cron Rule: The Cron Rule matches based on a cron expression. It allows you to define complex time-based rules.

• Sample Rule: The Sample Rule matches a percentage of requests. It is useful for A/B testing and other scenarios where you want to apply a rule to a subset of users.

• Query Rule: The Query Rule matches based on query parameters in the URL. It supports various operators such as:

  • EQUAL: Matches if the parameter equals a specific value.
  • NOT_EQUAL: Matches if the parameter does not equal a specific value.
  • MORE_THAN: Matches if the parameter is greater than a specific value.
  • MORE_THAN_OR_EQUAL: Matches if the parameter is greater than or equal to a specific value.
  • LESS_THAN: Matches if the parameter is less than a specific value.
  • LESS_THAN_OR_EQUAL: Matches if the parameter is less than or equal to a specific value.

• Language Rule: The Language Rule matches based on the user’s language. It uses the ISO 639-1 language codes.

Note

Rules are evaluated in the order they are defined. Make sure to define your rules in the correct order to achieve the desired behavior.

Rule Behaviors

Rule behaviors define what happens when a rule matches. There are three types of behaviors:

Redirect Behavior

The Redirect Behavior redirects the user to a specified URL with a specific status code. The status codes can be:

• 301: Moved Permanently
• 302: Found
• 307: Temporary Redirect
• 308: Permanent Redirect

Response Behavior

The Response Behavior responds with a specific content type and status code. The content types can be:

• application/json
• text/html
• text/plain

Template Behavior

The Template Behavior renders a template with the specified context. It allows you to use reusable content structures. Learn more about templates in the Templates documentation.

Examples

Redirect US Users

{
  "domain": "smart-l.ink",
  "id": "/example",
  "rules": [
    {
      "type": "COUNTRY",
      "version": 1,
      "country": "US",
      "behavior": {
        "type": "REDIRECT",
        "version": 1,
        "location": "https://example.com/us",
        "statusCode": "301"
      }
    },
    {
      "type": "BASIC",
      "version": 1,
      "behavior": {
        "type": "REDIRECT",
        "version": 1,
        "location": "https://example.com",
        "statusCode": "301"
      }
    }
  ]
}

JSON Response for Mobile Users

{
  "domain": "smart-l.ink",
  "id": "/example",
  "rules": [
    {
      "type": "DEVICE",
      "version": 1,
      "deviceType": "mobile",
      "bot": "EXCLUDE",
      "behavior": {
        "type": "RESPONSE",
        "version": 1,
        "contentType": "application/json",
        "statusCode": "200",
        "body": "{\"message\": \"Welcome mobile user!\"}"
      }
    }
  ]
}

Template for Business Hours

{
  "domain": "smart-l.ink",
  "id": "/example",
  "rules": [
    {
      "type": "CRON",
      "version": 1,
      "expression": "0 9-17 * * *",
      "behavior": {
        "type": "TEMPLATE",
        "version": "^1.0.0",
        "name": "business-hours",
        "context": {
          "message": "Welcome! Our business hours are from 9 AM to 5 PM."
        }
      }
    },
    {
      "type": "BASIC",
      "version": 1,
      "behavior": {
        "type": "TEMPLATE",
        "version": "^1.0.0",
        "name": "business-hours",
        "context": {
          "message": "Sorry, we are currently closed. Our business hours are from 9 AM to 5 PM."
        }
      }
    }
  ]
}

Redirect Based on Query Parameter

{
  "domain": "smart-l.ink",
  "id": "/example",
  "rules": [
    {
      "type": "QUERY",
      "version": 1,
      "rules": [
        {
          "param": "promo",
          "operator": "EQUAL",
          "value": "summer2023"
        }
      ],
      "behavior": {
        "type": "REDIRECT",
        "version": 1,
        "location": "https://example.com/summer-promo",
        "statusCode": "302"
      }
    }
  ]
}

Plain Text Response for Chrome users

{
  "domain": "smart-l.ink",
  "id": "/example",
  "rules": [
    {
      "type": "DEVICE",
      "version": 1,
      "browser": "Chrome",
      "behavior": {
        "type": "RESPONSE",
        "version": 1,
        "contentType": "text/plain",
        "statusCode": "200",
        "body": "Hello, Chrome user!"
      }
    }
  ]
}

Render a Linktree

{
  "domain": "smart-l.ink",
  "id": "/example",
  "rules": [
    {
      "type": "BASIC",
      "version": 1,
      "behavior": {
        "type": "TEMPLATE",
        "version": "^1.0.0",
        "name": "linktree",
        "context": {
          "links": [
            {
              "title": "Home",
              "url": "https://example.com"
            },
            {
              "title": "About",
              "url": "https://example.com/about"
            },
            {
              "title": "Contact",
              "url": "https://example.com/contact"
            }
          ]
        }
      }
    }
  ]
}

Customized Greeting for Chrome and Firefox Users

{
  "domain": "smart-l.ink",
  "id": "/example",
  "rules": [
    {
      "type": "DEVICE",
      "version": 1,
      "bot": "INCLUDE",
      "browser": "Chrome",
      "behavior": {
        "type": "RESPONSE",
        "version": 1,
        "contentType": "text/plain",
        "statusCode": "200",
        "body": "Hello, Chrome user!"
      }
    },
    {
      "type": "DEVICE",
      "version": 1,
      "bot": "INCLUDE",
      "browser": "Firefox",
      "behavior": {
        "type": "RESPONSE",
        "version": 1,
        "contentType": "text/plain",
        "statusCode": "200",
        "body": "Hello, Firefox user!"
      }
    }
    {
      "type": "BASIC",
      "version": 1,
      "behavior": {
        "type": "RESPONSE",
        "version": 1,
        "contentType": "text/plain",
        "statusCode": "200",
        "body": "Hello, user!"
      }
    }
  ]
}

A/B Testing Example

{
  "domain": "smart-l.ink",
  "id": "/example",
  "rules": [
    {
      "type": "SAMPLE",
      "version": 1,
      "rate": 50,
      "behavior": {
        "type": "RESPONSE",
        "version": 1,
        "contentType": "text/html",
        "statusCode": "200",
        "body": "<h1>Welcome to Version A!</h1><p>This is the first variant of our test.</p>"
      }
    },
    {
      "type": "BASIC",
      "version": 1,
      "behavior": {
        "type": "RESPONSE",
        "version": 1,
        "contentType": "text/html",
        "statusCode": "200",
        "body": "<h1>Welcome to Version B!</h1><p>This is the second variant of our test.</p>"
      }
    }
  ]
}

These examples illustrate various ways to use rules and behaviors to customize the user experience based on different conditions.