Customer Authentication

When a customer is logged in, the LoyaltyLion SDK needs to authenticate them to display their information (points, rewards) and allow them to perform actions like earning points and claiming rewards.

Authentication in LoyaltyLion leverages your existing customer accounts so a customer doesn’t need to sign in twice or have a separate account with LoyaltyLion.

It works by generating a secure server-side Message Authentication Token (MAC) which is passed through to LoyaltyLion on the next page load. LoyaltyLion verifies the auth token and if it checks out, considers the customer authenticated.

Creating the auth token

The auth token is a SHA-1 hash of the following concatenated items, in order:

• the customer’s unique id
• the current date, as an ISO 8601 timestamp
• the customer’s email address
• your LoyaltyLion secret

This auth token must be generated server-side, that is, in your template. Your LoyaltyLion secret should never be exposed. The generated token can then be sent to the client and used in a call to loyaltylion.init or loyaltylion.authenticateCustomer to authenticate the customer.

Auth token creation example

date = DateTime.now.iso8601
secret = 'YOUR_SECRET'

auth_token = Digest::SHA1.hexdigest(
  current_user.id.to_s + date + current_user.email + secret
)

Authentication with initialization

The best way to authenticate the customer is by passing the customer and auth data to the loyaltylion.init call. This ensures the customer is authenticated as soon as the LoyaltyLion SDK is ready.

You should call loyaltylion.init conditionally on the customer’s logged in state, that is, passing just the site token (initialize example without customer) if a customer isn’t logged in, or passing the customer information and authentication data (initialize example with customer) if a customer is logged in.

The date passed in the auth object must be the same timestamp used to generate the auth token.

Authentication after initialization

If you need to authenticate the customer later, for example if they’re able to log in without a full page reload, or authentication happens after the page load, you still need to call loyaltylion.init at the same time as loading the snippet, with just the site token and no customer information. You can later pass the customer information and authentication data in the loyaltylion.authenticateCustomer method.

This method accepts the same customer and auth properties as loyaltylion.init. It needs a server-side generated auth token.

The date passed in the auth object must be the same timestamp used to generate the auth token.

Authentication after initialization example

loyaltylion.authenticateCustomer({
  customer: {
    id: '1001', // unique customer ID
    email: 'alice@example.com', // customer email address
  },
  auth: {
    date: '2018-01-01T10:00:00Z', // ISO 8601 timestamp, must be same as that used to create the token
    token: 'AUTH_TOKEN', // token, generated server-side
  },
})

Logging a customer out of LoyaltyLion

You can log out a customer using the logoutCustomer method. This removes the signed-in customer’s data and refreshes the LoyaltyLion UI without requiring a full page reload. This can be particularly useful for single page applications (SPA) that support customers logging in / out without full page reloads. Note that this is an asynchronous method. If no customer is currently signed in you will see a warning message in the console.

// with async/await
await loyaltylion.logoutCustomer()

// with promises
loyaltylion.logoutCustomer().then(() => {
  console.log('Customer is logged out!')
})