Skip to main content

Customer Login

The Spiff Commerce platform provides an addon called the Conversion Accelerator. This addon allows you to retrieve customer details, and use them to improve conversion rates. This page will walk you through the process of authenticating a customer.

Requesting a Workflow Experience​

You'll first want to ensure you've created a client. See Getting Started for more information.

warning

To use the customer authentication features, you will need to specify the applicationKey when creating the client.

Authenticating a customer​

This process can be completed before, but not after, requesting the workflow experience. If you do it before, the customer will automatically be assigned as an owner of the transaction.

If you wish to associate a customer to an experience that is currently open, refer to Customer Details.

For relaunching a workflow experience, refer to Returning to an existing transaction.

Verifying a customer exists​

You may want to ensure the customer exists against your partner. You can do this by calling getOrCreateCustomer on the client. This will return a customer object, and a boolean indicating whether the customer is authenticated. If the customer is authenticated, their details will be assigned internally, so you can skip the rest of this section.

const {
    customer, // The customer object. You may not need this, but it's useful for storing the customer's identifier for later use.
    isAuthenticated, // Whether the customer is authenticated. This can be false if the customer is new, or has not logged in on this device before.
} = await client.getOrCreateCustomer(emailAddress);

Verifying a customer's email address​

If the customer is not authenticated, or you wish to manually re-authenticate, you'll need to get the Spiff Commerce API to send them a verification email. You can do this by calling generateVerificationCode on the client. This will send an email to the customer, with a verification code for them to enter.

// This can raise an error if the input email address is invalid. You'll need to handle this appropriately.
client
    .generateVerificationCode(emailAddress)
    .then(() => {
        // Verification code sent successfully.
    })
    .catch((error) => {
        // Handle the error here.
    });

Next, provide a way for the user to input their verification code, then call verifyCode on the client. This will verify the code, and return a boolean indicating whether the customer is authenticated. If the customer is authenticated, their details will be assigned internally.

// This function should only raise an error if the email address is invalid.
// It's fairly safe to assume that this should not happen if you're disabling the input field once they have reached this step.
const isAuthenticated = await client.verifyCode(emailAddress, verificationCode);

Returning to an existing transaction​

You may first wish to check if the customer has logged in on this device before. This can be achieved by calling authenticateTransactionFromLocalStorage on the client. This will return a boolean indicating whether the authentication was successful, a boolean indicating whether the transaction has been marked as read-only, and a string/enum indicating the type of stakeholder the customer is.

const {
    customLogoLink, // The custom logo link for the customer. This will be only be provided if the authentication was unsuccessful.
    stakeholderType, // The type of stakeholder the customer is. This will be undefined if the authentication was unsuccessful.
    success, // Whether the authentication was successful. This will be false if the customer has not logged in on this device before.
    theme, // The color and font options for the workflow. This will be only be provided if the authentication was unsuccessful.
    transactionReadOnly, // Whether the transaction has been marked as read-only. This will be true if the transaction has been ordered, and undefined otherwise.
} = await client.authenticateTransactionFromLocalStorage(transactionId);

If for any reason the authentication fails, you can defer to the authentication process. Once that is complete, you can retrieve the stakeholder type by calling getStakeholderTypeForTransaction on the client.

// This will return undefined if the customer is not authenticated.
const stakeholderType = await client.getStakeholderTypeForTransaction(transactionId);

Bundles​

If a transaction is part of a bundle the above process will function as normal, however the stakeholder information will be stored against the bundle instead of the transaction.

If you wish to authenticate the customer against the bundle, you can do so by calling authenticateBundleFromLocalStorage on the client. This will return a boolean indicating whether the authentication was successful, and a string/enum indicating the type of stakeholder the customer is.

See the page on Bundles for more information on how to create and manage bundles.

const {
    success, // Whether the authentication was successful. This will be false if the customer has not logged in on this device before.
    stakeholderType, // The type of stakeholder the customer is. This will be undefined if the authentication was unsuccessful.
} = await client.authenticateBundleFromLocalStorage(bundleId);

Additional Customer Information

Once you've authenticated a customer against the core client, you can always get the customer object by calling

// The customer object has general details like id, emailAddress, firstName, lastName, etc.
const customer = client.getCustomer();

Metafields​

Some customers may have additional data stored against them in the form of Metafields.

// Customer must be authenticated for the current session for this to succeed.
const metafields = await client.getCustomerMetafields();
const keyValues = metafields.map((metafield) => ({
    value: metafield.value, // The value of the metafield is always a JSON string, e.g. `"text"`, `true`, `1`, etc.
    key: metafield.metafieldConfiguration.name
}));