Handle Visitors with the JavaScript SDK

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

Create a Wix client with the OAuth strategy. 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.

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.

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().

The method returns an object in this format:

Save the tokens to your preferred storage:

Step 4 | Make API calls

Call Wix API methods using your client.

Example

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

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():

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:

Validate or renew existing tokens

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

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:

Check login status

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

See also

• About Handling Visitors
• OAuthStrategy API Reference
• Handle Members with a Custom Login Page