Skip to main content

Customer login and sharing a bundle with a stakeholder

In this tutorial you'll authenticate a customer, list the bundles they can access, and share a bundle with another person by adding them as a stakeholder. You'll also change and remove their access.

Requires the Conversion Accelerator add-on

Customer authentication and stakeholders are part of the Conversion Accelerator add-on. It must be enabled for your account before the calls in this tutorial will work, and you will need to contact us to enable it. The feature is still in active development.

Before you begin​

You'll need a SpiffCommerceClient constructed with your applicationKey, which is required for customer authentication. See Getting Started with the Core SDK.

1. Check whether the customer is already signed in​

Ask the client for the customer by email address. It creates the customer if they don't exist yet, and tells you whether they are already authenticated on this device.

const { customer, isAuthenticated } = await client.getOrCreateCustomer(emailAddress);

If isAuthenticated is true, skip to step 3.

2. Verify the customer's email address​

Otherwise, send the customer a verification code, then verify the code they enter. generateVerificationCode throws if the email address is invalid.

await client.generateVerificationCode(emailAddress);

// Show an input for the code, then:
const verified = await client.verifyCode(emailAddress, verificationCode);
if (!verified) {
    // The code was wrong. Let the customer try again.
}

Once verified, the customer is stored on the client and can be read back with client.getCustomer().

tip

Authenticate the customer before creating or loading a bundle, so that requests for the bundle are made on their behalf.

3. List the customer's bundles​

getBundleStakeholders returns one stakeholder entry for each bundle the signed-in customer has access to.

const stakeholders = await client.getBundleStakeholders();

const rows = stakeholders.map((stakeholder) => ({
    bundleId: stakeholder.bundle?.id,
    name: stakeholder.bundle?.name,
    role: stakeholder.type, // Owner, Approver, Editor or Viewer.
}));

For performance, only the stakeholder's id and type, and the bundle's id, name, createdAt and metadata, are returned.

4. Open a bundle and check the customer's role​

Reload the bundle, then ask which stakeholder the current customer is. It returns undefined if they have no access.

const bundle = await client.getExistingBundle(bundleId);
const current = await bundle.getCurrentStakeholder();

if (!current) {
    // The customer has no access to this bundle.
}

5. Share the bundle​

Add another person with addStakeholder. The email address is required and the other details are optional. The second argument is the role, which defaults to Owner, so pass it explicitly when sharing.

import { StakeholderType } from "@spiffcommerce/core";

await bundle.addStakeholder(
    {
        emailAddress: "colleague@example.com",
        firstName: "Sam", // Optional
        lastName: "Jones", // Optional
        phoneNumber: "1234567890", // Optional
    },
    StakeholderType.Viewer,
);

The roles are Owner, Approver, Editor and Viewer. Write access to the bundle is required to change its stakeholders. If the person is already a stakeholder, their details and role are updated.

6. See who has access​

const all = await bundle.getAllStakeholders();
all.forEach((stakeholder) => {
    console.log(stakeholder.customer?.emailAddress, stakeholder.type);
});

7. Change or remove access​

To change someone's role, call addStakeholder again with the same email address and the new role.

await bundle.addStakeholder({ emailAddress: "colleague@example.com" }, StakeholderType.Editor);

To remove someone, pass their email address to removeStakeholder.

await bundle.removeStakeholder("colleague@example.com");

To replace the whole list in one call, use updateStakeholders. Entries that aren't in the bundle are added, and existing stakeholders missing from the array are removed.

await bundle.updateStakeholders([
    {
        customerDetails: { emailAddress: "owner@example.com" },
        type: StakeholderType.Owner,
    },
    {
        customerDetails: { emailAddress: "colleague@example.com" },
        type: StakeholderType.Viewer,
    },
]);

Next steps​

  • Read Customer Login for customer metafields and returning to an existing bundle.
  • Read Customer Details for the full stakeholder reference.
  • Use duplicateBundle to let a customer start a new design from an existing one. See Bundles.
Last updated on