Contentful Integration

How to configure the SiteSpect App in Contentful

To use the SiteSpect App in Contentful you’ll designate certain entries in Contentful as being associated with a particular test experience. SiteSpect will assign users to the campaigns and variation groups, and the designated Contentful content will be displayed for your users in a test.

Required Changes on Origin

Look for headers in the format X-SST-# (where “#” is a positive integer). Each of these headers will have a positive integer value. These correspond to a SiteSpect campaign and variation group assignment within that campaign.

For example, “X-SST-123: 456” denotes the user is in campaign ID 123 and assigned to variation group 456.

SiteSpect Usage

1. Create a new campaign with the following configuration:
   1. Origin Type
   2. Remove the default trigger
   3. Set the origin factor to “header”, and check “Visible only to the origin”.
   4. In the 3-dot menu, uncheck the “disable campaign if…” option
   5. Disable counting for this variation (look for the silhouette icon)
2. Save the campaign (we need the campaign saved so we can find the ID).
3. After the save, find the ID for the campaign in the URL. Let’s say it's ID is 123. Set the header name to X-SST-123.
4. Now click the “Show IDs” button and note the ID of the variation group (NOT the variation!). For each variation group (including control!), set the header value to that VG’s ID.
5. Finally, you need to create another variation that will be used for counting.
   1. Make a new blank variation with a “parameter” trigger, with the following values:
      1. Parameter Name (regex): ^event(_\d+)?$
      2. Parameter Value (exactly): count-campaign-123
   2. Ensure counting is "on" for this variation
6. Change “123” to the actual ID of the campaign. Leave the search and replace for this factor blank. 

To turn counting on/off for a variation, toggle the silhouette icon:

Contentful Usage

You’ll create Campaign Association entries that correspond with your SiteSpect campaign. You should create one Campaign Association for each variation group. You can use whatever title you like, but it should be something that will help you identify which campaign and variation group it applies to.

Important! Make sure that whatever experiences you want to be shown by default have “IsOriginal” set to “Yes.” If a visitor is not assigned to a particular campaign, they will still see the entry if it’s marked as the original. If you do not mark any campaign associations as original, any user not assigned to an associated campaign will not see anything at all.

Filtering Entries

If you’re using a SiteSpect-provided library, you’ll pass the entries to the SiteSpect library along with a list of the user’s campaign assignments. For example, if you currently have code that looks like this:

const entries = await client.getEntries({ content_type: "blogPost" });

displayEntries(entries);

You’d modify that as follows:

const entries = await client.getEntries({ content_type: "blogPost" });

const filtered = SiteSpectContentfulFilter({

    entries,

    assignments: sitespectAssignments,

    counting: countingFunc,

});

displayEntries(filtered);

You also need to set up a counting function which is passed into the SiteSpectContentfulFilter. This function will be called with a Set object containing the IDs of all campaigns for which the user should be counted.

If you’re performing the filtering yourself, you’ll need to filter each entry according to the following rules. For clarity, I’ll refer to the entry currently being evaluated as the “candidate”.

The candidate should be shown if and only if at least one of the following statements is true:

• The candidate has no Campaign Association entries attached to it (i.e. there is no campaignAssociations field; or there is but the field is empty).
• The candidate has at least one attached Campaign Association which is an exact match for a variation group the visitor is assigned to (i.e. Campaign ID and Variation Group ID are both exact matches). This campaign should be considered “countable”
• The candidate has at least one Campaign Association which satisfies all of the following criteria.
• The Campaign Association is marked as an original (isOriginal = true)
• The visitor is not assigned to that campaign (i.e. for all of the visitor’s assignments, the campaign ID of the assignment does NOT match the campaign ID of this original Campaign Association

If the entry is not filtered out, you should further go through its fields and filter any other referenced entries by the same rules as above.

In addition to the filtering, you’ll also need to tell SiteSpect which campaigns are countable (i.e. which campaigns that the user is assigned to and for which they saw at least one variation).

Counting Function

Here is a sample counting function. This will take the set of campaign IDs for which the visitor should be counted and create an EventTrack request.

const countingFunc = campaignIdsSet => {

    const values = [...campaignIdsSet].map(id => `count-campaign-${id}`);

    SS?.EventTrack.rp(values);

};

For example, let’s say you’ve got: 

campaignIdsSet = new Set([12, 34, 56]) 

Passing that into this function will create an event track request like:

/__ssobj/track?event0=count-campaign-12&event1=count-campaign-34&event2=count-campaign-56

Client-side configuration

One-time setup

Add the following JavaScript to your page:

const siteSpectAssignments = {};

Create a new campaign variation with the following parameters:

• Page Source Trigger:

  const siteSpectAssignments = \{\};

• Search:

  const siteSpectAssignments = \{\};

• Replace:

  const siteSpectAssignments = {__SS_LISTCAMPAIGN{"__SS_TCID__":__SS_VGID__}{,}__};

This campaign variation will replace the line of code up above with an object that you can pass directly into the SiteSpect filter library.

Campaign creation

When you create your campaign, follow the guide above except…

• You do NOT need to make the origin factor. You only need the “counting” factor (the one with the parameter triggers)
• Make sure you add the campaign variation above to the campaign