Skip to end of metadata
Go to start of metadata

Server-side campaigns gives you the ability to integrate Evergage testing and personalization at the server to server level. While the Evergage Platform handles the campaign logic, a developer is required to write the code to call the appropriate APIs and provide Evergage with the necessary information about the user.

It works like this: Your servers call the Evergage server-side campaign API, providing information about the visitor (typically user ID). With that information, Evergage handles the campaign logic and returns recommendations and other campaign data (in JSON format) that applies to that visitor. Your server is responsible for handling the JSON and building the message to show the visitor, as well as calling the appropriate action tracking APIs to track campaign impressions and clicks.

This Article Explains

This article details how to create a server-side campaign.

Sections in this Article


Using Evergage's UI to Create a Server-Side Campaign


Create a Server-Side Campaign

Server-side messages are created at the Campaign level in the Evergage platform.

  1. Log into the Evergage platform
  2. In the Channels & Campaigns section, hover over Web, then select Server-Side Campaigns 
  3. Click New Campaign




Create a Server-Side Campaign Message

  1. Enter a Target
  2. Click Add New to insert a new row 
  3. Define a key, value pair under the Name  and Value   column.
  4. A value can be returned as quoted text by selecting Text as Type, or Number to be formatted as an unquoted number. See below on how to configure Promoted Content
  5. Insert dynamic content queries in the Value column by clicking a value in the grid, then selecting an option from the Dynamic+ dropdown. 
  6. Dynamic Message Content is not supported in Name, only as values.
  7. Click the Copy To All to copy all values in the row to all experiences in the campaign.
  8. Select Delete will remove that row from all experiences.




Configure Promoted Content

  1. Configure Promoted Items in Message Settings if the message contains any Promoted Content types.

  2. Name can be anything, Value should be $items and Type Promoted Content to return all applicable items in a JSON array.


“Name” can be anything, “Value” should be $items and “Type” Promoted Content to return items in JSON format


ADMC

  • Can return ADMC in text or number format (configured by “Type”). Provide default value (I don’t remember the syntax to give an example) or the message will fail to render if no values are found


Notes:

  • Dynamic Message Content not supported in “Name”, only as values

  • Insert Dynamic Message Content with dropdown by clicking in a Value, then selecting an option from the dropdown






Preview the Message

You can preview the rendered JSON message:

  1. Click Preview
  2. Under Experience, choose an experience to preview
  3. Select a Test User to view JSON that would return for the user
  4. The message will be under the "dataMap" key




Using Evergage UI to Setup A/B Tests, Targeting, and Recommended Content


Set up A/B Tests or Rule-Based Targeting

Click on the orange SETUP button and Experiences to access this interface. Here you can:

  1. Clone the Experience you made
  2. Set up A/B tests and control percentages
  3. Target experiences based on rules



Control the whole Campaigns Targeting Rules and Goals

Click on the orange SETUP button and Campaign Settings to access this interface. Here you can:

  1. Setup the Goals for this particular campaign (Remember all campaigns are auto-attributed against your Global Goals)
  2. Target all experiences in the campaign to particular segments
  3. Schedule the Campaign



Control the Campaign Schedule

It is easy to control the campaign schedule through this UI. 



Calling Evergage's Server-Side Campaign Endpoint



Overview

Server-side campaign event HTTP requests should use the path of your account-specific sscreceiver endpoint, which is:


https://<account-key>.evergage.com/sscreceiver


  • See table below for more information on request parameters

  • Refer to   Send Events Server-side Using HTTP Requests  for more information sending HTTP requests and required parameters

  • (Optional) Include segment IDs in the segment membership (".sm") parameter to return segment memberships for the user in the response. Including only the segment membership parameter without the specific segment IDs will return all IDs of segments the user is a member of.

  • Most parameters are optional, but as much information about the user and user behavior should be sent along the campaign request



Example response for a named user
{
  "campaignResponses": [
    {
      "campaignCreated": 1531756833995,
      "campaignId": "VtARR",
      "campaignName": "Clone of Standard Home Hero",
      "campaignType": "ServerSide",
      "displayMode": "Personalize",
      "experienceId": "QAoO8",
      "experienceName": "A",
      "hidePageBeforeRedirect": false,
      "id": "VtARR",
      "priority": 0,
      "saveParameters": false,
      "serverSideMessages": [
        {
          "campaignState": "Published",
          "containsDynamicContent": true,
          "dataMap": {
            "imageUrl": "http://retail.solida.evergage.com/magento/media/catalog/product/cache/1/image/9df78eab33525d08d6e5fb8d27136e95/m/i/michonne_evening_bag.png",
            "recommendedItems": [
              {
                "_id": "bgw0021",
                "attributesUpdated": 1530641306981,
                "categories": [
                  {
                    "_id": "Women|Handbags",
                    "type": "c"
                  }
                ],
                "created": 1484080519670,
                "currency": "USD",
                "dailyStats": [
                  {
                    "date": 1531699200000
                  }
                ],
                "description": "Satin. Silver hardware. Inside open pocket. Magnetic closure with foldover flap, fabric lining. 10\" x 2.5\" x 4\". Domestic.",
                "dimensions": {
                  "Brand": [
                    "Prada"
                  ],
                  "Gender": [
                    "Female"
                  ],
                  "ItemClass": [
                    "Bags & Luggage"
                  ]
                },
                "imageUrl": "http://retail.solida.evergage.com/magento/media/catalog/product/cache/1/image/9df78eab33525d08d6e5fb8d27136e95/m/i/michonne_evening_bag.png",
                "inventoryCount": 1,
                "locked": false,
                "name": "Michonne Evening Bag",
                "pregeneratedItemTemplateIds": [
                  "3Bs1j",
                  "6VBQe",
                  "ArXvl",
                  "ChSNu",
                  "GcR6h",
                  "UsRXI",
                  "emrS3"
                ],
                "pregeneratedItemTemplateMetadata": [
                  {
                    "attributesUpdated": 1530641306981,
                    "generationTime": 1530641567386,
                    "id": "3Bs1j"
                  },
                  {
                    "attributesUpdated": 1530641306981,
                    "generationTime": 1530641567594,
                    "id": "6VBQe"
                  },
                  {
                    "attributesUpdated": 1530641306981,
                    "generationTime": 1530641567735,
                    "id": "ArXvl"
                  },
                  {
                    "attributesUpdated": 1530641306981,
                    "generationTime": 1530641567959,
                    "id": "ChSNu"
                  },
                  {
                    "attributesUpdated": 1530641306981,
                    "generationTime": 1530641568162,
                    "id": "GcR6h"
                  },
                  {
                    "attributesUpdated": 1530641306981,
                    "generationTime": 1530641568264,
                    "id": "UsRXI"
                  },
                  {
                    "attributesUpdated": 1530641306981,
                    "generationTime": 1530641568524,
                    "id": "emrS3"
                  }
                ],
                "price": 450.0,
                "relationships": [
                  {
                    "itemRelationshipKey": {
                      "itemRelationshipType": "Static",
                      "itemType": "Product",
                      "linkedItemId": "hbm003 ",
                      "relationshipName": "Accessories"
                    }
                  }
                ],
                "tags": [
                  {
                    "_id": "Prada",
                    "tagType": "Brand",
                    "type": "t"
                  },
                  {
                    "_id": "Bags & Luggage",
                    "tagType": "ItemClass",
                    "type": "t"
                  },
                  {
                    "_id": "Female",
                    "tagType": "Gender",
                    "type": "t"
                  }
                ],
                "type": "p",
                "updated": 1531756002246,
                "url": "http://retail.solida.evergage.com/magento/michonne-evening-bag.html"
              },
              {
                "_id": "hdb006",
                "attributesUpdated": 1517406765062,
                "categories": [
                  {
                    "_id": "Home & Decor|Bed & Bath",
                    "type": "c"
                  }
                ],
                "created": 1484080534670,
                "currency": "USD",
                "description": "20\" x 20\". Printed polyester. Hidden zipper closure. Interior pillow included. 100% polyester fill. Spot clean. Imported.",
                "imageUrl": "https://madisonisland.evergage.com/magento/media/catalog/product/cache/1/image/9df78eab33525d08d6e5fb8d27136e95/h/d/hdb006_1.jpg",
                "locked": true,
                "name": "Shay Printed Pillow",
                "pregeneratedItemTemplateIds": [
                  "3Bs1j",
                  "6VBQe",
                  "ArXvl",
                  "ChSNu",
                  "GcR6h",
                  "UsRXI",
                  "emrS3"
                ],
                "pregeneratedItemTemplateMetadata": [
                  {
                    "attributesUpdated": 1517354911274,
                    "generationTime": 1517355048944,
                    "id": "3Bs1j"
                  },
                  {
                    "attributesUpdated": 1517354911274,
                    "generationTime": 1517355049085,
                    "id": "6VBQe"
                  },
                  {
                    "attributesUpdated": 1517354911274,
                    "generationTime": 1517355049198,
                    "id": "ArXvl"
                  },
                  {
                    "attributesUpdated": 1517354911274,
                    "generationTime": 1517355049354,
                    "id": "ChSNu"
                  },
                  {
                    "attributesUpdated": 1517354911274,
                    "generationTime": 1517355049489,
                    "id": "GcR6h"
                  },
                  {
                    "attributesUpdated": 1517354911274,
                    "generationTime": 1517355049592,
                    "id": "UsRXI"
                  },
                  {
                    "attributesUpdated": 1517354911274,
                    "generationTime": 1517355049745,
                    "id": "emrS3"
                  }
                ],
                "price": 210.0,
                "type": "p",
                "updated": 1531756732612,
                "url": "https://madisonisland.evergage.com/magento/shay-printed-pillow.html",
                "validated": 1511383617659
              },
              {
                "_id": "hbm005",
                "attributesUpdated": 1517406765062,
                "categories": [
                  {
                    "_id": "Home & Decor|Books & Music",
                    "type": "c"
                  }
                ],
                "created": 1484080580663,
                "currency": "USD",
                "description": "Falling by  I Am Not Lefthanded. Album: Yes Means No. Running time 3:16. Downloadable as mp3.",
                "imageUrl": "https://madisonisland.evergage.com/magento/media/catalog/product/cache/1/image/9df78eab33525d08d6e5fb8d27136e95/l/e/lefthanded.png",
                "isProduct": true,
                "locked": true,
                "name": "Falling by I Am Not Lefthanded",
                "pregeneratedItemTemplateIds": [
                  "3Bs1j",
                  "6VBQe",
                  "ArXvl",
                  "ChSNu",
                  "GcR6h",
                  "UsRXI",
                  "emrS3"
                ],
                "pregeneratedItemTemplateMetadata": [
                  {
                    "attributesUpdated": 1505788787184,
                    "generationTime": 1505789097526,
                    "id": "3Bs1j"
                  },
                  {
                    "attributesUpdated": 1484080997954,
                    "generationTime": 1484081407585,
                    "id": "6VBQe"
                  },
                  {
                    "attributesUpdated": 1505765938639,
                    "generationTime": 1505766052522,
                    "id": "ArXvl"
                  },
                  {
                    "attributesUpdated": 1484080997954,
                    "generationTime": 1484081408004,
                    "id": "ChSNu"
                  },
                  {
                    "attributesUpdated": 1484080997954,
                    "generationTime": 1484081408164,
                    "id": "GcR6h"
                  },
                  {
                    "attributesUpdated": 1484080997954,
                    "generationTime": 1484081408322,
                    "id": "UsRXI"
                  },
                  {
                    "attributesUpdated": 1484080997954,
                    "generationTime": 1484081408528,
                    "id": "emrS3"
                  }
                ],
                "price": 2.0,
                "skuIds": [
                  "558"
                ],
                "skuMap": [
                  {
                    "id": "558"
                  }
                ],
                "type": "p",
                "updated": 1531756646427,
                "url": "https://madisonisland.evergage.com/magento/falling-by-i-am-not-lefthanded.html",
                "validated": 1511383626384
              }
            ],
            "testGroup": "A",
            "url": "http://retail.solida.evergage.com/magento/michonne-evening-bag.html"
          },
          "id": "CKV5V",
          "promotedItemKeys": [
            {
              "_id": "bgw0021",
              "type": "p"
            },
            {
              "_id": "hdb006",
              "type": "p"
            },
            {
              "_id": "hbm005",
              "type": "p"
            }
          ],
          "targetName": "Home Hero",
          "type": "evg_md"
        }
      ],
      "state": "Published",
      "userGroup": "Control"
    }
  ],
  "errorCode": 0
}





Request Parameters


Parameter

Title

Optional?

Description

_ak

Evergage account ID


Identifier of your account in Evergage (same as your subdomain .evergage.com).

_ds

Evergage dataset ID


Identifier of your dataset in Evergage

_time

Event time

Optional

Event timestamp in epoch milliseconds. Optional–if omitted, current time is used.

userId

ID of the user


ID of the named user to associate with this event

.anonId

ID of an anonymous user


ID of the anonymous user to associate with this event. Either this or userId is required.

_anon

Is anon event


Set this to true to indicate that the event is from an anonymous user

company

Company/account of user

Optional

For datasets tracking accounts, this identifies which account the user belongs to. If omitted, user's existing account association will be used.

action

Action name


Name of the action that the user just took.

<custom>

Custom attribute

Optional

Specify any additional custom attributes for the user or account that you wish to set.

url


Optional

Url of the page the user is currently viewing

urlref

Referrer Url

Optional

The third-party referring URL that directed the user to this page, if any

clientIp


Optional

The client's IP address

.pv

Page view

Optional

Presence of this indicates the event represents a page view

.sm

Segment Membership

Optional

Return segment memberships for the user in the response. Including only the segment membership parameter without the specific segment IDs will return all IDs of segments the user is a member of.

.item


Required for item actions and if campaign requires an anchor item

The item JSON (see below for an example) of the item the user is viewing/purchasing/performing an action on. Required to qualify the user for campaigns configured with recommendations that requires an anchor item (co-browse, similar items, co-buy, etc)



Handle the campaign JSON

Calling the /sscreceiver endpoint will return any applicable server-side campaigns the user qualifies for in JSON format.

Be sure to check if the user is in the control group and not display the campaign for those users.  Users in the control group for a campaign if the “userGroup” value is “Control”, otherwise the value would be “Default”.

The JSON response will also include some metadata on the user in addition to campaign data. If the segment membership (".sm") parameter is present in the request, the response will include a “segmentMemberships” key that contains the segment IDs of the segment the user is a member of (see table above for more info)

Example of an item json for a Product, denoted by “‘type’: ‘p’”:

{"_id":"Pms003","categories":[{"_id":"Men|Shirts","type":"c"}],"currency":"USD","d":"Button-front. Imported. Available in checkered Blue. Cotton. Machine wash.","isProduct":true,"name":"Carroll Check Dress Shirt","price":160,"skus":{"816":{"a":[],"id":"816"}},"tags":[{"_id":"Shirts","type":"t","tagType":"ItemClass","name":"Shirts"},{"_id":"Male","type":"t","tagType":"Gender","name":"Male"},{"_id":"new","type":"t","tagType":"Badge","name":"new"}],"type":"p","url":"http://retail.solida.evergage.com/magento/carroll-check-dress-shirt-817.html","imageUrl":"http://retail.solida.evergage.com/magento/media/catalog/product/cache/1/image/9df78eab33525d08d6e5fb8d27136e95/p/m/pms003a_4.jpg"}




Tracking Campaign Impressions and Sending them to Evergage


In order for Evergage to provide campaign statistics and effectively manager Server-Side campaigns, you must track and return to Evergage the campaign impressions, clicks. and other relevant events. 

This section describes how to call the appropriate action tracking APIs to track campaign impressions and clicks.

  • To track a campaign impression, you should POST to Endpoint: /msreceiver
  • Track an impression on the campaign

    • Must also track an impression on the campaign if the user is in the control group. Don’t track click and dismissal events for the campaign if the user is in the control group

    • If the campaign contain recs, track that the user viewed the items. See details on “piks” below

  • Track user's clicks

    • If a user clicks on the campaign or an item on the campaign, track a click event

  • Track a dismissal if the user dismisses the rendered campaign without performing any action



Required Parameters

Parameter

Title

Description

_ak

Evergage account ID

Identifier of your account in Evergage (same as your subdomain .evergage.com).

_ds

Evergage dataset ID

Identifier of your dataset in Evergage

userId or .anonId


ID of the user to associate with this event. Set userId for a named user or .anonId for an anonymous user. Also set _anon=true if the event is from an anonymous user

.cStat

campaignStat

This parameter is a JSON array containing a list of campaign metadata representing a message, or experience campaign action. See below for how to structure the payload


.cStat parameters

  • For each campaign, track an impression on the Experience and each message in the experience that the user saw. The .cStat would contain one impression on the experience of a campaign and one impression for each message in the experience, and may have multiple experiences or campaign stat events if more than one campaigns are displayed on the page. You do not have to specify the campaign ID

  • type

    • Expected values: “e” (experience) or “m” (message)

    • .cStat may only contain one object with type “e”

  • id

    • Id of the experience if type is “e”, or of the message if type is “m”

  • eid

    • The experience Id. Only required for tracking message stats - if the type is“m”

  • stat

    • Expected values: “i” (Impression), “c” (click), or “d” (Dismissal)

  • ug

    • User group

    • Only required if the user is in the control group. Set userGroup to “Control”, otherwise omit this parameter

  • href

    • Only required if campaign action is a click event (type=”c”)

  • piks

    • JSON array of Promoted Item keys - only populated for message stats - “type”: “m”.

    • Promoted Item Key object:

    • _id

      • id of the item

    • type

      • type of the item

      • Single character, such as “p” for “Product” or

      • Refer to “promotedItemKeys” in the campaign response for the correct type

  • Example of an impression on two campaign experiences:

    • .cStat=[{"type":"e","id":"ZcupW","stat":"i"},{"type":"m","id":"XrQUC","stat":"i","eid":"ZcupW"},{"type":"e","id":"AvBdc","stat":"i"},{"type":"m","id":"agdGd","stat":"i","eid":"AvBdc"}]]


  • Example of .cStat unencoded value in a request to track impression on a campaign with promoted items

    • .cStat=[{"type":"e","id":"ZcupW","stat":"i"},{"type":"m","id":"XrQUC","stat":"i","eid":"ZcupW", “piks”: [{"type":"p","_id":"bgw0021"},{"type":"p","_id":"hbm005"}]}]

Testing

Besides previewing through the UI, preview an experience for a user using a URL:

https://<ACCOUNT_KEY>.evergage.com/sscreceiver?.testMessages=<EXPERIENCE_ID>&_ak=<ACCOUNT_KEY>&_ds=<DATASET_KEY>&_ne=true&userId=<USER_ID>

Note: set "_ne=true" to avoid track the test event.



Campaign Statistics and Analytics in Evergage


Detailed Event Analysis

Detailed events sent to Evergage can be studied to troubleshoot

Access this by clicking on the event stream





Summary Campaign Statistics

Summary Campaign statistics are available in the campaign overview screen



Detailed Campaign Statistics and Analysis

Detailed Campaign statistics are available by clicking on any campaign in the overview screen.

  • See Lift over Control for all Global Goals and Campaign Specific Goals
  • Confidence using Bayesian statistics
  • Analyze by click vs view attribution. 
  • Analyze impact for different segments. 
  • Change the attribution window
  • Look at different time periods



Catalog Stats are also updated 




Examples of Server-Side Campaigns


Experience A Setup

With an ALS Recipe

Example of what JSON will return for user f003822a2b46882e, shown in Preview and by calling test URL below:




Experience B Setup


With a static promoted content for an Avery Oxford Shirt

Example of what JSON will return for user f003822a2b46882e, shown in Preview and by calling test URL below






Notice different results for keys “imageUrl” and “recommendedItems” because Promoted Content is different for experience A and B.

For experience A “recommendedItems” is populated with items determined by configured the recipe


The JSON returned by the test urls above is the same JSON in the Preview