PrimedJS

Create a personalized web application that is unique and relevant for each and every user with the PrimedIO personalizer for JavaScript.

Use

Signature

PrimedIO uses HMAC-authentication to secure communication between end-user client-side (javascript / mobile) and server-side. The use case is slightly more complicated than usual, as the service does not operate in the same domain as that serves the application to the end-user. For this reason, HTTPS is required to encrypt data in motion and no plain-text secret keys are sent over the line. The approach is loosely based on how AWS secures S3.

Each PrimedIO personalize call expects a server-side generated signature to be passed along with the request, using the following form:

var pubkey = "1234567890"; // replace this with your public key
var secretkey = "abcdefghijklm"; // replace this with your secretkey
var nonce = 1519207397; // replace this with the actual UTC seconds from epoch, i.e. DateTime.now() or equivalent

var signature = sha512(pubkey + "" + secretkey + "" + nonce);

// results in the following signature:
"61f8e93826f2ce34f5eae3e7085c478b3e8653bc902f363177da15334ddf6e1ee976b2b66aa487a1d0166912d2d6efc00eb168670517c1f6baaa609d5d32f111"

The signature can then be passed to the client-side code along with the page itself, to be picked up by the PRIMEDIO.init() call.

Initialization

PRIMED.init(
	new Date().toISOString(), 	// this needs to be an ISO8601 formatted UTC string
	"<your public key>", 		// PrimedIO provides you with a public key
	"<your signature>" 		// the HMAC signature generated server-side using your public key, private key and timestamp
);

Personalisation

Personalisation requires at least a campaign key (NB, this is not the campaign name), e.g. mycampaign.recommendations. We also need to know which A/B variants are available (by label) and which fractions of traffic we want to assign to each. An example personalize call looks as follows:

PRIMED.personalize(
	function(result) { doSomething(result) },	// callback function for when the personalise results return
	function(err) { dealWithError(); }, 		// callback function in case something goes wrong
	"mycampaign.recommendations", 			// campaign key for which personalisation is called
	['2503001'], 					// list of signals (itemId currently being viewed, deviceId, location, etc.)
	5, 						// number of desired results (can be empty in case of no match on any signal)
	["__CONTROL__", "A", "B"], 			// available A/B variants as configured by datascientists in PrimedIO
	[0.1, 0.45, 0.45] 				// fraction of traffic desired for each A/B variant
);

N.B. the reason we are demanding the client to determine the A/B variants enables session persistent A/B testing. This means that at the beginning of a session the website code can decide which group this session belongs to and have this group membership persist throughout the session.

N.B. the current implementation of the client allows the developer to not specify A/B variants and fractions, upon which case it will set defaults. These defaults currently are the following: [”__CONTROL__“, “A”, “B”] and [0.2, 0.4, 0.4]. This will be deprecated as soon as possible, so future development is strongly recommended to provide values for these parameters.

Conversion

Upon successful personalisation, a list of results will be returned. Each result will contain a variable payload: the idea here is that PrimedIO is generic and supports freeform Targets, which can be item ID’s (usually used in lookups after the personalize call), URL’s, Boolean values, and any combination of these. Additionally, each result will contain a unique GUUID, randomly generated for this particular call and Target. It is used to track the conversion of this particular outcome, which we use to identify which of the A/B variants performed best. Conversion is also generic, but generally we can associate this with clicking a particular outcome. In order for PrimedIO to register this feedback, another call needs to be made upon conversion:

PRIMED.convert(
	"GUUID to convert"	// the GUUID belonging to the result which we want to mark as converted
);