The HTML API is optional, but can be useful for more advanced integrations.
How it works
The HTML API is based around inserting a single hidden HTML tag in your HTML. Normally the data is encrypted using a shared secret.
This example shows it in plain text:
<div id="__tmsd"
e="customers_email_address@none.none"
cid="39439493"
style="display: none;">
Once encrypted using RC4 and base64 encoded, the example would look like this:
<div id="__tmsd"
e="g7XzaUB8PrC+rmWHo3CVBzreZdzZYdXmspRrKbd/FCc="
cid="0/m0LhYlYvE="
style="display: none;">
Attributes table
Name | Description |
e | Email address for the current site visitor. |
cid | Customer ID for the current site visitor. This is usually 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 | Session ID for the current cart session. |
nomail | If set to |
perm | If set to |
All data being passed to Fresh Relevance in the e, cid and s attributes can - and usually should - be encrypted. To do this, you need to specify a shared secret on the settings page and then use this key to encrypt using RC4 and then base64 encoded. There are some code samples below for this in some popular scripting languages.
Code samples - RC4 encryption
Here are some code samples to use on your web server. They can be run from the command line for testing purposes:
You can also try our RC4 test page. Learn more in Test RC4 encryption.
PHP example
<?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";
?>
Python example
## {{{ http://code.activestate.com/recipes/576736/ (r5)
#!/usr/bin/env python
#
# RC4, ARC4, ARCFOUR algorithm
#
# Copyright (c) 2009 joonis new media
# Author: Thimo Kraemer <thimo.kraemer@joonis.de>
#
# 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