Handle Visitors

Once you've created a client, your client can generate, manage, and use tokens for anonymous site visitors. The client uses these tokens when making requests to Wix APIs on behalf of a visitor to maintain the visitor's session.

When you create a client, new visitor tokens are automatically generated and set to the client, creating a new visitor session, if you don't specify that the client should use existing tokens. If you want a new client to resume a previous visitor session, you need to provide the client with the tokens previously used in that session.

Once tokens are set for a client, the client manages the tokens, generating new access tokens when necessary, without you needing to do anything. However, if you want, you can manually handle visitor tokens as well.

Prerequisites

• Create a project
• Create an OAuth app for visitors and members
• Create a client with OAuth

Generate new visitor tokens

A client will automatically generate new visitor tokens if you don't pass any tokens to it when you create the client.

1

Alternatively, use a client's generateVisitorTokens() method to generate an access token and a refresh token for an anonymous visitor.

1

The function returns a promise that resolves to an object containing:

• An access token with an expiration time in epoch timestamp format. Use this to resume the visitor's session. Access tokens expire after 4 hours.
• A refresh token for generating a new access token. Use this when the access token expires.

For example:

1

Store tokens for later

If you want to be able to restore the current session at some point later, store your client's tokens locally, for example in localStorage, a cookie, or a local file.

Get a client's current tokens using getTokens() or generate new ones using generateVisitorTokens().

Confirm or renew an access token

Once you have tokens, they are mostly managed by the client. If you want to manually confirm or renew an access token you can pass your tokens as arguments to generateVisitorTokens().

1

• If the access token passed is still valid, generateVisitorTokens() returns the existing valid access token and refresh token.
• If the access token has expired but the refresh token is valid, generateVisitorTokens() returns the existing refresh token and a newly generated access token.
• If the refresh token is not valid, generateVisitorTokens() returns a new refresh token and a new access token.

Alternatively, you can use renewToken() to generate a new access token for an existing refresh token without checking whether the existing access token is valid.

1

Resume a visitor's session

If you already have visitor tokens, you can use them to resume a visitor's session.

You can resume a session when creating a client by passing it existing tokens, as in this example that reads the tokens from a cookie.

1

Or, if you already have tokens and a client, you can resume a visitor session by calling setTokens() to set the tokens as the active tokens for your client.

1

Once tokens are set, every call made by your client uses these tokens. This means that the visitor's data is preserved and associated with these tokens. For example, items added to a cart, or tickets the visitor reserves, are reflected in future calls made by a client using the same tokens.

Retrieve tokens

To retrieve the tokens currently set to the client, use getTokens().

1

Example

1