Dynamic Content | In Depth

There are four components to keep in mind as we use Joystick Dynamic Content. We will discuss each of these in detail.

1. The request from your application.
2. The config that is stored in Joystick.
3. The optional Dynamic Mapping that can be enabled for each config.
4. The response back to your application.

Declaring Content for Segmentation or AB Testing

The first step is to declare the content you would like to be dynamic for segmentation or AB Test. Declarations are made directly in your config JSON using a simple syntax.

Declaration Syntax

Declaring String, Number or Boolean

{
    "my_string": "#LK-SimpleString:string:Hello!#",
    "my_number": "#LK-SimpleNumber:number:12345#",
    "my_boolean": "#LK-SimpleBoolean:boolean:true#"
}

As soon as you enter the declarations, the editor in Joystick will recognize it, then show you the default values it parsed.

Declaring Objects or Arrays as Dynamic Content

{
    "my_object": "#LK-SimpleObject:object:my_object#",
    "my_array": "#LK-SimpleArray:array:my_array#",
    "_dynamic_values_": {
        "my_object": {},
        "my_array": []
    }   
}

You can make entire objects or arrays also dynamic.

1. Add a special object to the root of your content called _dynamic_values_. This is where the default values for arrays and objects be picked up from.

2. The default value should be a key that corresponds to the array or object in _dynamic_values_.

   About _dynamic_values_

   The "_dynamic_values_" object will be removed when sending the response back to you. It will NOT appear when requesting your content over API.

The _dynamic_values_ object will be highlighted in the editor.

The Dynamic Content Map

When you have identified and declared the components you would like to segment or ab-test in your content, you can now create the Dynamic Map. The Dynamic Map is the rule-set that determines how your content is transformed.

Click Add Dynamic Map when you are editing a piece of content to open up the Dynamic Map Editor panel.

[
  {
    "expression": "location = 'ch'",
    "name": "offer_title_test",
    "info": "Optional, additional info.",
    "activationDateTime": {
      "start": "2022-01-01T01:01:01Z",
      "end": "2099-12-31T23:34:45Z",
      "overrideAndActivateNow": false
    },
    "groups": [
      {
        "variantName": "variant_a",
        "mod": [
          [ 0, 199 ]
        ],
        "values": {
          "LK-OfferTitle": "Extra Special Offer"
        }
      }
    ]
  }
]

Expression

The expression parameter makes Joystick Dynamic Content extremely versatile and flexible. On the p object in your request, you can send along different parameters, which can then be used in the expression.

• When the expression evaluates to true then the content the content replacement of the group it is in will be processed.
• You can have multiple groups that all evaluate to true. Content replacement is processed in priority from top to bottom.

or, ||
and, &&
!, not, ~ (bitwise not)
=, ==, !=, <>
<, <=, >, >=
+, -, *, /, %
& (bitwise and), | (bitwise or), ^ (bitwise xor), << (left shift), >> (right shift)

Expression Example

{
    "u": "USER ID OR GUID",
    "p": {
        "myString": "hello",
        "myStringArray": ["one", "two", "three"],
        "myNumber": 10,
        "myNumberArray": [1, 2, 3] 
    }
}

Given that the body sent with the config is the same as above, here are some examples to show you how expressions work.

"expression": "myString == 'hello'" // true
"expression": "(myNumber * 2) == 10 " // false
"expression": "myString == 'hello' and myNumber >= 10" // true (Use logical operators to combine statements)
"expression": "StringIn('one', myStringArray) and myNumber < 20" // true (Check if 'one' is a member of myStringArray)
"expression": "NumberIn(6, myNumberArray)" // false
"expression": "in(myString, 'hello', 'goodbye')" // true (Is the first argument in hard-coded list)
"expression": "if(myNumber > 20, true, myString == 'goodbye')" // false (Using an if statement)

Controlling AB Testing or Staged Rollout using Mod

With Joystick you can control and place your users into stable ab test groups.

• Based on the "u" parameter sent on the request body, we will generate a corresponding stable integer between 0 and 999 inclusive. The same "u" will always be transformed into the same integer.
• To expose only a partial group of your audience to a variation, you can use groups[n].mod to define the ranges which will be given a particular treatment.
• You define a 'band' of users to expose using a pair of integers between 0 and 999. The numbers are inclusive. Each increment of 1 represents 0.1% of your audience.

Examples with Explanation

"mod": [[0,0]] // This will expose 0.1% of your audience

"mod": [[500,599]] // This will expose 10% of your audience.

"mod": [[200,299], [800,899]] // This will expose two separate 'bands' of your audience for a total of 20%.

You can run multiple simultaneous AB tests by exposing different non-overlapping 'bands' of your audience. An example of this is shown below.

[
    {
        "expression": "1 = 1"
        // Other params not shown
        "groups": [
            {
                "mod":[ [200,249] ] // 5% test group.
                // Other params not shown
            }
        ]
    },
    {
        "expression": "1 = 1"
        // Other params not shown
        "groups": [
            {
                "mod":[ [700,799] ] // 10% test group.
                // Other params not shown
            }
        ]
    },
]

Dynamic Content: Extended Example and Explanation

This example demonstrates the functionality and flexibility of Joystick Dynamic Content. Both the Dynamic Map and Content are shown.

[
  {
    "expression": "location = 'ch'",
    "name": "offer_title_test",
    "info": "Optional, additional info.",
    "groups": [
      {
        "variantName": "variant_a",
        "mod": [
          [
            0,
            199
          ]
        ],
        "values": {
          "LK-OfferTitle": "Extra Special Offer"
        }
      },
      {
        "variantName": "variant_b",
        "mod": [
          [
            500,
            599
          ],
          [
            700,
            899
          ]
        ],
        "values": {
          "LK-OfferTitle": "A Very Good Offer!"
        }
      }
    ]
  },
  {
    "expression": "days_in_app >= 7",
    "name": "improved_offer",
    "info": "Optional, additional info.",
    "values": {
      "LK-Price": 2.99,
      "LK-BundleItems": { "coins": 100, "gear": ["hammer", "tent", "portable-stove"] }
    }    
  }
]

{
  "SpecialPricingOffer":
  {
    "OfferTitle": "#LK-OfferTitle:string:Special Offer#",
    "Price": "4.99",
    "BundleItems": "#LK-BundleItems:object:bundle_items#"
  },
  "_dynamic_values_":
  {
    "bundle_items":
    {
      "coins": 50,
      "gear": ["backpack"]
    }
  }
}

There are two segments defined in the Dynamic Map (two objects in the main array).

1. "expression": "location = 'ch'"
   • This one is named "offer_title_test", and will match if the 'location' parameter passed in on the request is the string 'ch'.
   • There are two ab-test variants.
   • variant_a is exposed to 20% (mod range 0 to 199 inclusive) of the audience, and the title "Extra Special Offer" will be shown.
   • variant_a is exposed to 30% (mod range 500 to 599 and 700 to 899) of the audience, and the title "A Very Good Offer!" will be shown.
2. "expression": "days_in_app >= 7"
   • This one is named "improved_offer", and will match if the 'days_in_app' parameter passed in on the request is a number equal or greater than 7.
   • There is no ab-test for this segment. When there is no ab-test, the "values" object can be placed at the same level as "expression".
   • There are two parameters to be replaced if this segment is matched.
     • LK-Price will be replaced with 2.99
     • LK-BundleItems will be replaced with a bigger bundle.
   • Notice how the groups parameter is not required if you have the values parameter.

Complete Example

Below is a complete example showing what each component looks like.

// This is the config that is stored in Joystick. It has a dynamic content declaration.
{
    "SpecialPricingOffer": {
        "OfferTitle": "#LK-OfferTitle:string:Special Offer#",
        "PercentBonus": "10",
        "Price": "4.99",
        "BackgroundColor": "LightGreen",
        "ButtonColor": "LightSalmon",
        "ButtonActionText": "Buy Now"
    }
}

// This is the dynamic content map that pairs with the Config Content.
[
  {
    "expression": "location = 'ch'",
    "name": "offer_title_test",
    "info": "Optional, additional info.",
    "groups": [
      {
        "variantName": "variant_a",
        "mod": [
          [
            0,
            199
          ]
        ],
        "values": {
          "LK-OfferTitle": "Extra Special Offer"
        }
      },
      {
        "variantName": "variant_b",
        "mod": [
          [
            200,
            499
          ]
        ],
        "values": {
          "LK-OfferTitle": "Offer Just For You!"
        }
      }
    ]
  }
]

// This is the body of the request to the Joystick REST API.
{
  "u": "d",
  "p":
  {
    "location": "ch"
  }
}

// This is the response back over REST API
{
  "data":
  {
    "SpecialPricingOffer":
    {
      "OfferTitle": "Extra Special Offer",
      "PercentBonus": "10",
      "Price": "4.99",
      "BackgroundColor": "LightGreen",
      "ButtonColor": "LightSalmon",
      "ButtonActionText": "Buy Now"
    }
  },
  "hash": "e35b02af",
  "meta":
  {
    "uid": 655955059,
    "mod": 59,
    "seg":
    [
      {
        "n": "offer_title_test",
        "i": "Optional, additional info.",
        "v": "variant_a"
      }
    ]
  }
}