HTML API overview

The HTML API allows you to pass information from your cart page or other web page to Fresh Relevance.

This is an optional feature, but can be useful for more advanced integration.

The HTML API is based on inserting a single hidden DIV tag in your HTML with the following attributes populated:

Attribute	Optional	Description
e	No	Email address for the current site visitor.
cid	No	Customer ID for the current site visitor. This will usually be a reference for the account on your shopping cart. If there are several IDs, choose the one used in the API provided by your cart.
s	No	Session ID for the current cart session.
nomail	Yes	If set to "1", "true" or "checked", Fresh Relevance will not trigger any emails for this person.
perm	Yes	If set to "1", "true" or "checked", this person has given consent to receiving marketing emails. If set to "0", "false" or "unchecked", this person has withdrawn consent.

Data Protection

All data being passed to Fresh Relevance in the e, cid, and s attributes can - and usually should - be encrypted. To encrypt data, specify a shared secret on the settings page (expand the User menu, and go to Settings > Security and Privacy > RC4 Encryption). Use this key to encrypt the values using RC4, then base64 encode them. Below are some code samples for this encryption process in popular scripting languages.

<?php

/*
 * RC4 symmetric cipher encryption/decryption
 *
 * @license Public Domain
 * @param string key - secret key for encryption/decryption
 * @param string str - string to be encrypted/decrypted
 * @return string

 From https://gist.github.com/2185197
 */
function rc4( $str, $key) {
	$s = array();
	for ($i = 0; $i < 256; $i++) {
		$s[$i] = $i;
	}
	$j = 0;
	for ($i = 0; $i < 256; $i++) {
		$j = ($j + $s[$i] + ord($key[$i % strlen($key)])) % 256;
		$x = $s[$i];
		$s[$i] = $s[$j];
		$s[$j] = $x;
	}
	$i = 0;
	$j = 0;
	$res = '';
	for ($y = 0; $y < strlen($str); $y++) {
		$i = ($i + 1) % 256;
		$j = ($j + $s[$i]) % 256;
		$x = $s[$i];
		$s[$i] = $s[$j];
		$s[$j] = $x;
		$res .= $str[$y] ^ chr($s[($s[$i] + $s[$j]) % 256]);
	}
	return $res;
}

/* This example shows how to encrypt a value to pass it to Triggered Messaging */
$encrypted = base64_encode(rc4("test","myprivatekey"));
$reversed = rc4( base64_decode($encrypted), "myprivatekey");
echo "Encrypted form in base64:\n";
echo $encrypted;
echo "\nReversed back to plain text:\n";
echo $reversed;
echo "\n";
?>

## {{{ http://code.activestate.com/recipes/576736/ (r5)
#!/usr/bin/env python
#
#       RC4, ARC4, ARCFOUR algorithm
#
#       Copyright (c) 2009 joonis new media
#       Author: Thimo Kraemer <[email protected]>
#
#       This program is free software; you can redistribute it and/or modify
#       it under the terms of the GNU General Public License as published by
#       the Free Software Foundation; either version 2 of the License, or
#       (at your option) any later version.
#
#       This program is distributed in the hope that it will be useful,
#       but WITHOUT ANY WARRANTY; without even the implied warranty of
#       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#       GNU General Public License for more details.
#
#       You should have received a copy of the GNU General Public License
#       along with this program; if not, write to the Free Software
#       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
#       MA 02110-1301, USA.
#

def rc4crypt(data, key):
    x = 0
    box = range(256)
    for i in range(256):
        x = (x + box[i] + ord(key[i % len(key)])) % 256
        box[i], box[x] = box[x], box[i]
    x = 0
    y = 0
    out = []
    for char in data:
        x = (x + 1) % 256
        y = (y + box[x]) % 256
        box[x], box[y] = box[y], box[x]
        out.append(chr(ord(char) ^ box[(box[x] + box[y]) % 256]))

    return ''.join(out)
## end of http://code.activestate.com/recipes/576736/ }}}


# This example shows how to encrypt a value to pass it to Triggered Messaging
import base64

encrypted = base64.b64encode(rc4crypt(data="test", key="myprivatekey"))
reversed = rc4crypt(data=base64.b64decode(encrypted), key="myprivatekey")
print "Encrypted form in base64:"
print encrypted
print "Reversed back to plain text:"
print reversed

HTML Example

We recommend that the data is encrypted using a shared secret. The following examples are in plain text to provide clarity.

<div id="__tmsd"
e="[email protected]"
cid="39439493"
style="display: none;">

Once encrypted using RC4 and base64 encoded, the example looks like this:

<div id="__tmsd"
e="g7XzaUB8PrC+rmWHo3CVBzreZdzZYdXmspRrKbd/FCc="
cid="0/m0LhYlYvE="
style="display: none;">