Getting started:: Installing the Loyalty Wallet – Emarsys

The Emarsys Loyalty Wallet is a full solution to a Loyalty program embedded in your website with very minimal javaScript. It provides the UI as well as everything else required to pull and push data to the Loyalty backend servers.

Overview

When the Loyalty Wallet initializes correctly, you will see the Wallet Status or Join button in their configured location in the online shop. If not, you should see an error message which you can send us to start troubleshooting.

Installation

To install the Loyalty SDK, you need to embed the following code in the shop code footer so that it is included in ALL pages in the online store (at least all that should show the Wallet).

This example is in PHP, and includes your appId and secret. Upon request, the code is available in other languages (Java, Go, Ruby, etc), too.

Please keep these settings safe, and in any case they are disclosed, let us know as soon as possible, so that we can change them.

<?php
// loyalty code
$appId = "123456789123456";
$customerId = "123456789123456";
$contactId = "sample1@loyalsys.io";
$serverSideSecretFromLoyalsys = "S0m3V3ryL0ngS3cr3t";
$timestamp = time(); // seconds since unix epoch
$language="en"  //optional: only needed if you have multiple languages, see below for more information
$currency="EUR" //optional: only needed when you have multiple currencies, see below for more information
$country="IT" // optional: only needed when you have multiple countries, see below for more information
$planId="online" //optional: only needed if you have multiplan, if you do put here the planId according to how you set it in the suite
$token = hash_hmac("sha256", $contactId . time() , $serverSideSecretFromLoyalsys) //generated server-side
?>


<script type="text/javascript">

window.loyalsysSettings =

{ appId: '<?php echo $appId ?>', contactId: '<?php echo $contactId ?>', timestamp: '<?php echo $timestamp ?>', token: '<?php echo $token ?>', region: "eu", language : '<?php echo $language  ?>', currency: '<?php echo $currency ?>', country: '<?php echo $country ?>', planId: '<?php echo $planId ?>'}

window.loyalsysSettingsEA =

{ appId: '<?php echo $appId ?>', customerId: '<?php echo $customerId ?>', contactId: '<?php echo $contactId ?>', timestamp: '<?php echo $timestamp ?>', token: '<?php echo $token ?>', region: "eu" , language : '<?php echo $language  ?>', currency: '<?php echo $currency ?>', country: '<?php echo $country ?>', planId: '<?php echo $planId ?>'}
!function()
{var e=(new Date).getTime(),t=document.getElementsByTagName("script")[0],n=document.createElement("script");n.src="https://ui-elements.loyalsys.io/v1.0.1/embed.min.js?x="+e,n.type="text/javascript",n.async=!0,n.defer=!0,t.parentNode.insertBefore(n,t)}

();
!function()
{var e=(new Date).getTime(),t=document.getElementsByTagName("script")[0],n=document.createElement("script");n.src="https://exaccess.loyalsys.io/v1.0.1/ls_ea.min.js?x="+e,n.type="text/javascript",n.async=!0,n.defer=!0,t.parentNode.insertBefore(n,t)}

();

</script>

For each shop visitor, set their userID (email or customerId) in the $contactId variable (set to sample1@loyalsys.io in the example). If the user is not logged in and there is no unique identifier yet, then pass an empty string.

The identifier you use in your webshop for the parameter $contactId needs to be the same identifier you use in Emarsys for your sales data (the customer field).

Parameters:

$customerId : This is your company’s identifier in Emarsys.
$appId : Provided to you by the Loyalty team at the time of integration.
$secret : Provided to you by the Loyalty team at the time of integration.

If your website supports multiple languages and currencies, use the following parameters:

$currency
$language

For each call to the JS send the required language and currency, according to their ISO codes.

If you have several websites or properties, one for each country, use the parameter $country. For each call to the JS, send the country code, according to the ISO code format.

In case you have multiple plans in your account, use the parameter $planId. This will identify for Loyalty to which of your plans the contact belongs to. The planId value is defined in your Account Settings as the Plan identifier. In case you do not send this parameter, the system assumes that the contact belongs to your default plan, the first plan configured in your suite. If you have only one plan, then you do not need to add this parameter at all to the call.

When using multiple plans, include the $planId parameter in the php part of the code to be embedded in your shop page.

...
$token = hash_hmac("sha256", $contactId . $planId . time() , $serverSideSecretFromLoyalsys) //generated server-side
?>

In case you have only one country, language and currency, omit these parameters and take them out from the JS call as in the following example:

window.loyalsysSettings =
{ appId: '<?php echo $appId ?>', contactId: '<?php echo $contactId ?>', timestamp: '<?php echo $timestamp ?>', token: '<?php echo $token ?>', region: "eu" }
window.loyalsysSettingsEA =
{ appId: '<?php echo $appId ?>', customerId: '<?php echo $customerId ?>', contactId: '<?php echo $contactId ?>', timestamp: '<?php echo $timestamp ?>', token: '<?php echo $token ?>', region: "eu" }

You should register these users in your shop as customers, and then try the example code above for them to see that you do not get any errors and that you see their points status.

On pages where you do not want the Loyalty Wallet to appear, simply do not include the above code. While this may seem obvious, you may need additional code for this logic, depending on your site structure.

Wallet override

In some cases, a website may want to override the Loyalty Wallet's regular behavior, and control its opening. For example, if the website has a link on its web page that should show the loyalty information.

Do the following to enable the Wallet control:

Suppress the automatic mechanism.

To suppress the automatic opening of the Wallet, add the following new flag (manualShow: true) to the embedded Wallet settings:

window.loyalsysSettings = {
 	appId: appId,
 	region: "eu",
 	contactId: contactId,        
 	timestamp: timestamp, // seconds since unix epoch
 	token: hashInHex , // token, generated server-side  
 	manualShow: true,          
   }

Trigger when the Wallet should open.

This can be done with a regular Javascript call:

   window.loyalsysSettings.ShowWallet()

Since the Wallet is loaded in an iFrame, you may want to pass a callback function to know when you can start calling it. For example:

   window.loyalsysSettings.onInit = () => {
   	console.log('Wallet is ready, and can now be opened')
   }

If you want to open the Wallet, as soon as the page is loaded, you can combine the above functionality with another line as the following:

   window.loyalsysSettings.onInit = () => {
   	window.loyalsysSettings.ShowWallet()
   }

Debugging

If you do not see the Wallet after installation, take a look in the browser console logs for any errors and let us know.

For more information on the Loyalty API, see the documentation.