Implementation:: Installing and testing the Loyalty Wallet, Exclusive Access and the API – Emarsys

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

Loyalty Wallet is available in the following languages: DE, EN, ES, FI, FR, HE, IT, NL, NO, PL, PT, SV, TR, ZH

If you do not find a language, please provide the translations and we introduce it as per your request.

Important:

Emarsys Loyalty is not responsible for authenticating users. To use the Loyalty Wallet or API, it is the client's responsibility to authenticate the users before using Loyalty.
The Loyalty Wallet does not support single-page application (SPA).

Loyalty Wallet

To use the Loyalty Wallet or Exclusive Access, you need to create Wallet credentials:

AppID
Secret key

Go to Loyalty Configurations > Loyalty Wallet and click Create AppID/Secret Key.

If your website works in multiple languages, it is enough to work with a single Wallet.

In case the same Emarsys account is connected to multiple websites, you could create multiple Loyalty Wallets (multiple credentials). This way you can create a matching wallet design for each website. In this case, give each Wallet credentials a description, so you can differentiate them.

You can also have one Wallet and multiple loyalty plans. The technical implementation explains that your developer has to send the plan identifier as one of the parameters. This way, loyalty knows to which plan to join the user.

To create the credentials, you need the following:

Emarsys Account Owner user role
Smart Insight
The systems checks if the configuration is done, otherwise, credentials cannot be created.

The reason for Smart Insight being a prerequisite is that Loyalty checks your contact identifier in Smart Insight. If it is predictuserid, Loyalty needs to use a different hashing algorithm.

In case you are using SSO to log in to your Emarsys account, you will not be able to create the credentials. You will need to open a ticket with Emarsys Support or speak to your Emarsys Implementation Consultant.

After you created your credentials, you have the option to:

Update the description field
Create a new Secret Key, in case you lost the old one.

If you create a new Secret Key, you need to update your website with it, otherwise the Wallet will stop working immediately after the creation of the new Key.

Option to disable or enable the Wallet. If you disable the wallet, it will immediately stop working on your website.
Option to delete all loyalty reporting data for users after their membership cancellation.

Send the credentials for the Loyalty Wallet including the link to the technical implementation to your development team.

When installing the code for the Loyalty Wallet (and Exclusive Access), one of the parameters to send is the user identifier. The identifier needs to be the same that you use in your sales data for Smart Insight as a unique identifier.

To access the unique identifier, go to Management > Smart Insight Settings > Contact Fields > Unique identifier.

Configurable parts of the Loyalty Wallet:

Text
Colour (one color for the whole wallet)
Font (only open-source fonts)
Logo
Links
Default tab, the Wallet should open: Earn/Redeem
The order of groups within the tabs

If you want to change any of the above points, please open a support ticket.

Loyalty Wallet and the Loyalty API will only work once you have launched your Loyalty plan for the first time.

After creating Loyalty Wallet credentials, you are not allowed to change the contact identifier for Smart Insight, this can cause the Loyalty system to work incorrectly. If you need to change the identifier, please contact Emarsys Support or your Client Success Manager or your Implementation Consultant first.

Checking if the Loyalty Wallet loads correctly

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 inside the developer console in the browser. If you need further help, ask your Implementation Consultant, or open a support ticket.

Error in the console

Loyalty API

Alternatively, you could use the Loyalty API, which provides the same functionality as the Wallet. This enables you to create your own UI which is natively integrated into your website.

The API requires the contactId parameter. Let your developer know that this is the externalid you use for the sales data in Smart Insight.

To use the API, go to Loyalty Configurations > API key and click Create API key.

To create the API key, you need:

To be the Emarsys Account owner
Smart Insight to be configured. The systems checks if the configuration is done, otherwise, the button will be greyed out. The reason for this is, that we check what is your contact identifier in SI. If it is predictuserid, Loyalty needs to use a different hashing algorithm.
You can have up to five API keys at the same time. If you already have five keys, the Create button becomes grey.

After creating the API key, you can edit it:

Updating the description of the key
Activating/Deactivating the key. When the key is deactivated, API calls to Loyalty will stop working.

For information about how to implement the API, please visit our developer page.

The Loyalty API will only work once you have launched your Loyalty plan for the first time.

After creating the API Key, you are not allowed to change the contact identifier for Smart Insight, this can cause the Loyalty system to work incorrectly. If you need to change the identifier, please contact Emarsys Support or your Client Success Manager or your Implementation Consultant first.

Testing

After you implemented the Wallet or the API, set up Tiers, Rewards and Actions, and finally launched your plan, you can start testing everything in your development environment.

We recommend you test the following:

The Wallet design and wording is correct
The Wallet is shown on the correct pages and to the desired users, namely, not to guest users
The correct identifier (external_id) is sent to the Wallet. This can be done by following steps:
1. Open your browser and go to your webshop (on development or staging).
2. Login to the webshop.
3. When you see the Wallet, press F12, or right-click with your mouse and go to inspect the element. You will see the following screen:

Switch to the Elements tab and search for the word: contactid. You should now find the Loyalty configuration under window.loyalsysSettings in the main window. Look for the parameter contactId. This should show the current user’s identifier used for the Wallet.
If you choose email as your identifier, you should see here the user’s email. This is to ensure that your development team is sending the correct externalid to Loyalty.
Contacts get their Join reward when they join the program
Links from the Wallet work: Login page, T&C’s, etc.
Fixed benefits and rewards are shown correctly
Points allocation for purchases: To be able to test that contacts will get points for purchases, ask your Implementation Consultant to check if sales data is being imported into Loyalty correctly.