Handle Visitors

Share your feedback
Reach out to us with feedback and suggestions to improve the Wix Headless experience, and join the Headless channel of the Devs on Wix Discord community to discuss features and connect with our growing community of developers.

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

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.

Copy
1
const myWixClient = wixApiClient.createClient({
2
modules: {
3
products,
4
services,
5
},
6
auth: wixApiClient.OAuthStrategy({
7
clientId: '<YOUR_CLIENT_ID>',
8
}),
9
});

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

Copy
1
const myTokens = await myWixClient.auth.generateVisitorTokens();

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:

Copy
1
{
2
accessToken: {
3
value: "OauthNG.JWS.eyJraWQiOi...3NbrhrauQ",
4
expiresAt: 1677581109
5
},
6
refreshToken: {
7
value: "JWS.eyJraWQiOiJZSEJzdUpwSCIsImFsZyI6IkhTMjU2In0.eyJkYXRhIjoiXCJkMDY4OTM4OS1kNTExLTRlYWMtYThjZC03MWQwMzA1NGIxM2NcIiIsImlhdCI6MTY3NzU2NjcwOSwiZXhwIjoxNzA5MTAyNzA5fQ.w2D7wECX_T-XfRzP4pXSoH8XSdHFBPnKx50FYzftRdc"
8
}
9
}

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

Copy
1
const myNewTokens = await myWixClient.auth.generateVisitorTokens(myOldTokens);
  • 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.

Copy
1
const myTokens = await myWixClient.auth.renewToken(<YOUR_REFRESH_TOKEN>);

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.

Copy
1
const myWixClient = createClient({
2
modules: { products, currentCart, redirects },
3
auth: OAuthStrategy({
4
clientId: '<YOUR_CLIENT_ID>',,
5
tokens: JSON.parse(Cookies.get('session') || null)
6
})
7
});

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.

Copy
1
myWixClient.setTokens(JSON.parse(Cookies.get('session') || null));

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

Copy
1
const myTokens = myWixClient.getTokens();

Example

Copy
1
import { createClient, OAuthStrategy } from '@wix/sdk';
2
import { cart } from '@wix/ecom';
3
import { products } from '@wix/stores';
4
5
const myWixClient = createClient({
6
modules: {
7
cart,
8
products,
9
},
10
auth: OAuthStrategy({
11
clientId: `<YOUR_CLIENT_ID>`,
12
}),
13
});
14
15
const myRefreshToken = MY_REFRESH_TOKEN || null; // Set to an existing refresh token, or to null if there isn't one.
16
const myAccessToken = MY_ACCESS_TOKEN || null; // Set to an existing access token, or to null if there isn't one.
17
18
const tokens = await myWixClient.auth.generateVisitorTokens({
19
accessToken: myAccessToken, // If invalid or null, a new access token will be generated.
20
refreshToken: myRefreshToken, // If invalid or null, a new refresh token and access token will be generated.
21
});
22
23
myWixClient.auth.setTokens(tokens); // Set the returned tokens to the client, so subsequent calls use these tokens.
24
25
// ...
26
27
// This cart is retained and can be accessed by a client with the same tokens:
28
const cart = await myWixClient.cart.createCart({});
29
30
// ...
31
32
const { items } = await myWixClient.products
33
.queryProducts()
34
.startsWith('name', 'shoes')
35
.limit(4)
36
.find();
Was this helpful?
Yes
No