Global Control Group (GCG) guide for client-side script and API

The Global Control Test is a method for measuring the overall impact of your experimentation program. The measurement is done using an A/B test that splits your overall traffic into two groups – users who receive personalized Dynamic Yield experiences and those who don’t – and compares them.

For example:

By comparing the performance of the Dynamic Yield Experiences and Control Group variations, we can estimate the total impact of experiences A, B, and C.

Setting up the Global Control Test

Step 1: Create the Global Control Test 

Create a Custom Code  campaign using the following settings:

1. Name the campaign Global Control Test.
2. Set the trigger as Page Load.
3. Set the frequency to Session.
4. Create an experience with the name Global Control Test.
5. Leave targeting conditions as they are, targeted to all users.
6. Create a variation called Dynamic Yield Experiences with the following JavaScript code:
   

   var GCG_STORAGE_NAME = '_dy_cs_gcg';
   var CG_VALUE = 'Control Group';
   var DY_VALUE = 'Dynamic Yield Experiences';
   var STORAGE_TYPE = 'cookieStorage';
   window.DYO.StorageUtils.remove(GCG_STORAGE_NAME, [STORAGE_TYPE]);
   window.DYO.StorageUtils.set(GCG_STORAGE_NAME, DY_VALUE, [STORAGE_TYPE]);

7. Create another variation called Control Group with the following JavaScript code:
   

   var GCG_STORAGE_NAME = '_dy_cs_gcg';
   var CG_VALUE = 'Control Group';
   var DY_VALUE = 'Dynamic Yield Experiences';
   var STORAGE_TYPE = 'cookieStorage';
   window.DYO.StorageUtils.remove(GCG_STORAGE_NAME, [STORAGE_TYPE]);
   window.DYO.StorageUtils.set(GCG_STORAGE_NAME, CG_VALUE, [STORAGE_TYPE]);
   

8. Set the allocation to 95% for Dynamic Yield Experiences and 5% for Control Group.
9. Publish the campaign after validating the stickiness is set to "Sticky for the user (multi-session)" inside the cogwheel icon.

Step 2: Create the evaluator

The evaluator is used to target experiences to the Dynamic Yield Experience group or the Control Group.

1. Create an evaluator with the name Global Control Test Group.
2. Set the value type to String.
3. Set Expected Values to Dynamic Yield Experiences and Control Group.
4. Insert the following code:

   (function () {
     return DYO.Q.Promise(function (resolve, reject) {
       var GCG_STORAGE_NAME = '_dy_cs_gcg';
       var STORAGE_TYPE = 'cookieStorage';
       window.DY.CS = window.DY.CS || {};
       if (window.DY.CS.inGlobalControl) {
         resolve(window.DY.CS.inGlobalControl);
         return true;
       }
       getGCCookie();
   
       function getGCCookie() {
         var GCValue = window.DYO.StorageUtils.get(GCG_STORAGE_NAME, [STORAGE_TYPE]);
         if (GCValue) {
           window.DY.CS.inGlobalControl = GCValue;
           resolve(GCValue);
         } else {
           setTimeout(function () {
             getGCCookie();
           }, 50);
         }
       }
     });
   })();

5. Save the evaluator.

Step 3: Add experiences to the Global Control Test

Adding experiences to the Global Control Test is an ongoing process. If you have a personalized experience, target it (using the evaluator you just created) to the Dynamic Yield Experiences group. This ensures that only users who are part of the 95% population grouping receive this experience. 

If the campaign required a default experience (served to all traffic, including the 5% control group), create the experience and serve it to the control group using the same evaluator. 

Best practices: What should you measure?

• Consult your Customer Success Manager to align on what personalization and testing efforts to include in order to best measure the value of your personalization program.
• Don't include experiences that have no effect on the user's experience.
  For example, firing an event or implementing a cookie.
• Don't include experiences that must be served and are not optimized. 
  For example, cookie consent notification.

Step 4: GCG for API campaigns

There are several options for implementing Global Control in API campaigns. Discuss with your account team which of the following options makes sense for you.

Option 1: Determine allocation in your codebase and pass it to Dynamic Yield

1. Implement code like the following example within your codebase so that it runs before the first API request to the Dynamic Yield choose endpoint. Check whether the user already has the "_dy_cs_gcg" cookie, and if not, you decide which version of GCG they receive:

   const express = require('express');
   const cookieParser = require('cookie-parser');
   const app = express();
   const port = 3000;
   
   app.get('/', (req, res) => {
     res.send('Hello World!');
   });
   
   app.use(cookieParser());
    
   app.use((req, res, next) => {
     if (!req.cookies._dy_cs_gcg) { // if a gcg value already exists
       const control_percentage = 5;
       const isControl = Math.floor(Math.random() * 100) < control_percentage;
       const gcValue = isControl ? 'Control Group' : 'Dynamic Yield Experiences'; 
       res.cookie('_dy_cs_gcg', gcValue, { // store a new gcg value cookie 
         expires: new Date(Date.now() + 31540000000000), // Set a 1 year expiration for the new cookie
       });
     }
     next();
   });
   
   app.listen(port, () => {
     console.log(`Example app listening on port ${port}`);
   });

2. Use the value of gcValue in the pageAttributes option of the choose request to tell Dynamic Yield whether this user should be placed into the Control Group or the Dynamic Yield Experience group. 

   curl --request POST \
       --url https://dy-api.com/v2/serve/user/choose \
       --header 'content-type: application/json' \
       --header 'DY-API-Key: baadc6ba740a352c9106dc7857a7eb9c' \
       --data '{
       "user": {
       "dyid": "-4350463893986789401",
       "dyid_server": "-4350463893986789401"
       },
       "session": {"dy": "ohyr6v42l9zd4bpinnvp7urjjx9lrssw"},
       "selector": {"names": ["PDP Top Banner"]},
       "context": {
       "page": {
       "type": "PRODUCT",
       "data": ["7383723-010"],
       "location": "https://sugoi-ne.com/men-pants/p7383723-010",
       "locale": "en_US"
       },
       "device": { 
       "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36",
       "ip": "54.100.200.255"
       }, 
       "pageAttributes": { "globalControlGroup": "Dynamic Yield Experiences" } 
       },
       }'

3. In your API campaigns, create two experiences: One for the campaign and one for control. Use the Custom Attribute targeting condition to target the experiences to their corresponding user groups.
4. In your response to the browser, set the correct value for the "_dy_cs_gcg" cookie as a response header, with a 1-year expiration date. This cookie can now be used by the Global Control Test Group evaluator created earlier for any client-side campaign targeting. If you don't implement client-side campaigns, this cookie is still necessary for your future targeting in API tests.

5. Where Dynamic Yield client-side scripts are implemented:

   1. Create a Custom Code campaign using the following settings:

   2. Name the campaign Global Control Test.
   3. Set the trigger as Page Load.
   4. Set the frequency to Session.
   5. Create an experience with the name Dynamic Yield Experiences.
      • Target this experience using the Global Control Test Group Evaluator to Dynamic Yield Experiences.
      • Add one variation with 100% traffic allocation containing the following code:

      • // Dynamic Yield Experiences

6. Create a second experience with the name Control Group.

• • • Target this experience using the Global Control Test Group Evaluator to Control Group.
    • Add one variation with 100% traffic allocation containing the following code:

    • // Control Group

7. Publish.

       Where Dynamic Yield client-side scripts are not implemented:

1. Create a Custom API Campaign using the following settings:
2. Name the campaign Global Control Test.
3. Create an experience with the name Dynamic Yield Experiences
   • Target this Experience using the Custom Attribute to Dynamic Yield Experiences.
   • Add one variation with 100% traffic allocation containing the following code:

   • { "Dynamic Yield Experiences" : "true" }

4. Create a second experience with the name Control Group.
   • Target this Experience using the Custom Attribute to Control Group.
   • Add one variation with 100% traffic allocation containing the following code:

   • {"Control" : "true" }

5. Publish.
6. Be sure to call this API campaign once per session for each user. You don't need to use the response of this call for anything, we are calling it to register an Impression with this campaign to have tracking for overall GCG performance. 

Option 2: Make an API request for the GCG before making other API requests

1. Make a new Custom API campaign and name the campaign Global Control Test.
2. Create an experience with the name Global Control Test.
3. Create a variation called Dynamic Yield Experiences with the following JSON:

   { "_dy_cs_gcg" : "Dynamic Yield Experiences" }

4. Create another variation called Control Group with the following JSON:

   { "_dy_cs_gcg" : "Control" }

5. Set the allocation to 95% for Dynamic Yield Experiences and 5% for Control Group.
6. Publish the campaign.
7. On the first pageview, check if the user already has the "_dy_cs_gcg" cookie, if they don't, make an API request for only the Global Control Test. Use the value of "_dy_cs_gcg" in the pageAttributes option of the choose request for the remaining campaigns on the page.
8. Use the Custom Attribute targeting condition to target the other API campaigns as seen in Step 3 of Option 1 above.
9. In your response to the browser set the correct value for the "_dy_cs_gcg" cookie as a response header, with a 1-year expiration date. Now this cookie can be used by the "Global Control Test Group" Evaluator created earlier for any client side campaign targeting.