Troubleshooting personalization and tracking events
If personalized pages don't render as expected or SitecoreAI analytics doesn't show the expected data, troubleshoot your application's personalization and tracking configuration.
This topic covers Content SDK 2.x Next.js applications. Personalization runs on the server through PersonalizeProxy. For real visitors, page view events run in the browser through the @sitecore-content-sdk/events package.
Verify personalization and tracking setup
Before troubleshooting requests, verify the following settings:
- Connect the application to the correct SitecoreAI environment and site. Verify the server context ID (
SITECORE_EDGE_CONTEXT_ID) and client context ID (NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID). Use the Live context when testing published content on the public site. See Connect your Content SDK app to SitecoreAI. - Assign an analytics identifier to the site and each language you want to track or personalize. Adding a language doesn't automatically assign an analytics identifier. See Manage personalization and analytics for sites.
- Publish the page and its personalized variants. Verify that the visitor meets the audience conditions for the variant you expect to display.
- In
src/proxy.ts, verify that the proxy chain includesPersonalizeProxyand passes it thesiteslist from.sitecore/sites.json,scConfig.api.edge, andscConfig.personalize. Run it afterMultisiteProxy(Pages Router) orAppRouterMultisiteProxy(App Router). For App Router applications,LocaleProxymust also run before personalization. Personalization uses the site and language these proxies resolve. Ensure that the proxy matcher includes the page you are testing and that any customskipcallback returnsfalsefor the request. - Verify that browser initialization includes
analyticsPluginwithanalyticsBrowserAdapter()andeventsPlugin(). In starter applications, this initialization is insrc/Bootstrap.tsx. See Initializing tracking, events, and personalization in the Content SDK. - Verify that the application renders
CdpPageViewand that your cookie consent implementation permits tracking for the test visitor.
Starter applications disable personalization and browser page view tracking in development mode. They also skip browser tracking in editing and preview modes. Test published content in normal rendering mode using a production build connected to SitecoreAI. PersonalizeProxy requires Experience Edge configuration and can't use local container API endpoints for personalization.
Personalized page rendering issues
The personalization proxy retrieves variant information from Experience Edge, then requests a personalization decision. If a request times out, the visitor sees the default page.
To troubleshoot the personalization proxy:
-
Enable debug logging by setting the following environment variable:
-
Restart the application, request the page, and inspect the server logs. Check the resolved site, language, request path, and any messages indicating that the proxy skipped the request.
-
Verify that the context IDs match the environment you are testing. Verify that
NEXT_PUBLIC_PERSONALIZE_SCOPEmatches thePAGES_PERSONALIZE_SCOPEenvironment variable in the connected SitecoreAI environment. Starter applications use the same configured scope for server-side personalization and browser page view events. -
Check for timeout errors before interpreting a skip message. An Experience Edge timeout produces a GraphQL client
response errorlog containing[IE-003] Timeout exceededimmediately beforeskipped (personalize info not found). For this error, adjustPERSONALIZE_MIDDLEWARE_EDGE_TIMEOUTas described in Configure personalization timeouts. For Sitecore CDP personalization timeouts, adjustPERSONALIZE_MIDDLEWARE_CDP_TIMEOUT.
Configure personalization timeouts
You can configure timeouts through environment variables or the personalize properties in sitecore.config.ts.
| Environment variable | Configuration property | Description | Default |
|---|---|---|---|
PERSONALIZE_MIDDLEWARE_CDP_TIMEOUT | personalize.cdpTimeout | Timeout for Sitecore CDP personalization requests, in milliseconds. | 400 |
PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUT | personalize.edgeTimeout | Timeout for Experience Edge requests that retrieve personalization information, in milliseconds. | 400 |
For example, to set a one-second timeout for each request, add the following values to your rendering host's environment configuration:
If you explicitly set personalize.cdpTimeout or personalize.edgeTimeout in sitecore.config.ts, those values take precedence over the corresponding environment variables. Update or remove the explicit values before testing an environment variable change. See The Sitecore configuration file.
Restart or redeploy the application after changing its configuration. Request the page again and review the logs to verify that the request completes within the new timeout.
Both timeout values use milliseconds. Increasing a timeout gives a request more time to complete, but can increase page response time. Adjust the value for the failing request based on the timings in your logs.
Personalization is skipped or the default variant appears
The default variant doesn't always indicate a timeout. Use the debug logs to identify the cause:
| Log message | What to check |
|---|---|
personalize proxy is disabled globally | Verify personalize.enabled in sitecore.config.ts. It defaults to false in development mode. |
personalize service not configured - edge config required | Verify that the application has Experience Edge context IDs configured. |
personalize info not found | First check the preceding log for response error containing [IE-003] Timeout exceeded. If present, follow Configure personalization timeouts to adjust the Experience Edge timeout. Otherwise, verify the requested site, route, language, and published content. |
no personalization configured | Verify that the published page contains personalization variants. |
no variant(s) identified | Verify audience conditions and that the personalization scope matches the connected SitecoreAI environment. For geolocation conditions, implement extractGeoDataCb in the PersonalizeProxy configuration in src/proxy.ts to supply the visitor's city, country, or region. The starter example is commented out; the proxy sends geolocation data only when the callback supplies it. |
preview, prefetch, or bot request | Test a normal page visit in a browser. The proxy skips these requests by design. |
Bot detection is available from Content SDK 2.1.0. When enabled, it skips personalization for bot traffic by default. See Lightweight tracking.
Missing or unexpected analytics data
To troubleshoot browser page view events:
-
Open the browser developer tools. Check the console for initialization errors and the Network tab for failed event requests. Inspect the response for details about the failure. For SDK error codes, see Troubleshooting.
-
Verify that
NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_IDbelongs to the environment you are testing and that browser initialization uses the correct site name. Rebuild and redeploy the Next.js application after changing public environment variables. -
Inspect the browser SDK configuration in the console:
These values show the analytics configuration, current client ID, and analytics and events library versions.
eventsPluginsetsevents.versionindependently of the analytics diagnostic properties. Use it to check whether browser initialization reachedeventsPlugin; its presence doesn't confirm that analytics initialization succeeded.If
analytics_coreis missing, check the following causes:- Browser initialization didn't run, or failed before
analyticsPlugincompleted initialization. analyticsPluginhasoptions.enableCookieset tofalse. It returns before setting the analytics diagnostic properties.- The client ID request failed. If Edge returns no client ID, initialization throws
[IE-005]. Check the browser console and Network tab for the failed request.
- Browser initialization didn't run, or failed before
-
If your application enables cookie-based tracking, check that the browser stores the
sc_cidcookie. Verify the configured cookie domain and whether the visitor's consent settings permit tracking. -
Verify that
CdpPageViewreceives route data and uses the page's variant ID, language, and configured personalization scope when creatingpageVariantId. -
Check that the analytics dashboard covers the correct site, analytics identifier, and date range. Sites or languages that share an analytics identifier can share analytics data.