In This Article

Handle Visitors with the JavaScript SDK

Note: This article is relevant for self-managed headless projects, and for Wix-managed headless projects built with a framework other than Astro. If you build with Wix's Astro integration, the CLI generates and manages visitor tokens for you automatically.

Use visitor tokens to maintain anonymous visitor sessions in your self-managed headless project. The SDK uses these tokens when making requests to Wix APIs on behalf of a visitor, preserving their data such as cart items or event reservations.

Step 1 | Create a client

Get your client ID from the Headless Settings of your project dashboard.

Tip: For Wix-managed headless projects, you can also find your client ID locally as the appId in your project's wix.config.json file.

Create a Wix client with the OAuth strategy using the client ID. Before creating the client, check your storage for tokens from a previous session:

Returning visitor: Tokens exist in storage. Pass them to the client to resume the previous session.
New visitor: No tokens found. Omit tokens when creating the client and generate new tokens as described in Step 2.

Copy

Note: Visitor and member authentication requires only a client ID, not a client secret. You need a client secret only to perform admin operations using the OAuth client_credentials flow.

Step 2 | Generate visitor tokens

Call generateVisitorTokens() and store tokens to persist the session.

Returning visitor: Visitor tokens expire after 4 hours, so you must ensure the stored tokens are still valid. The method returns the same tokens if they're still valid, or renewed tokens if they've expired.
New visitor: The method creates tokens for a new session. Alternatively, the client creates them automatically on your first API call. Calling generateVisitorTokens() initially lets you persist tokens if the app reloads before making your first API call.

Copy

Step 3 | Save tokens to persist the session

To persist a visitor's session across page reloads or app restarts, save the tokens to local storage, a cookie, or a file.

Retrieve the active tokens with getTokens().

Copy

The method returns an object in this format:

Copy

Save the tokens to your preferred storage:

Copy

Step 4 | Make API calls

Call Wix API methods using your client.

Note: If you create the client without tokens or skip Step 2, the client generates tokens automatically on your first API call. Make sure to retrieve and save the tokens as described in Step 3.

Copy

Example

The following example shows the complete visitor session flow, from creating a client to making API calls:

Copy

Manage tokens manually

In most cases, the client manages tokens automatically. Use these methods when you need manual control.

Set tokens on an existing client

If you already have a client instance and need to set tokens on it later, use setTokens():

Copy

Once tokens are set, the visitor's data is preserved. For example, items added to a cart or tickets reserved are reflected in future API calls.

Generate tokens explicitly

Call generateVisitorTokens() to create tokens before making any API calls:

Copy

Validate or renew existing tokens

Pass existing tokens to generateVisitorTokens() to confirm they're valid or renew them if expired:

Copy

The method returns:

The same tokens if the access token is still valid.
A new access token if the access token expired but the refresh token is valid.
New access and refresh tokens if the refresh token is invalid.

Force token renewal

Use renewToken() to generate a new access token without checking if the current one is valid:

Copy

Use loggedIn() to check if the current visitor is a logged-in member:

Copy