FAQ Beacon 2.0 Migration

Q: Why should I rush migrating to Beacon 2.0 if 1.0 is still working?

A: Beacon 2.0 significantly reduces "payload bloat." By removing the need to send full product metadata (like images and prices) in every event, you get faster page performance, lower browser overhead, and a much simpler integration to maintain. Additionally, we will retire the legacy infrastructure on March 31, 2027. All customers must be migrated to Beacon 2.0 by this date to ensure continued tracking and data continuity.

Q: What is the most critical technical change for my implementation?

A: Capturing the responseId. You must capture the responseId from the initial Recommendations API response and include it in your Beacon 2.0 data payloads. This is how our backend identifies which products were shown without you having to re-send all the metadata.

Q: How do I test my integration without messing up production analytics?

A: Use the new Developer Sandbox Mode. By adding "dev": "true" to the context object of your payload, you can validate your event pipeline. These events are validated for accuracy by our API but are filtered out of your production reports.

Q: What happens if I forget to turn off the dev flag before going live?

A: Your production performance reports will remain empty. Ensure this flag is removed or set to false for your production launch.

Q: How do I avoid CORS preflight (OPTIONS) requests to improve speed?

A: Set your Content-Type header to text/plain. Every Beacon 2.0 endpoint is designed to accept POST data as plain text, allowing you to skip the browser's preflight check and send data faster.

Q: How do I track impressions accurately for products in a carousel?

A: We recommend using the Intersection Observer API. Trigger the impression event only when a product card enters the visible area of the carousel (we suggest a threshold of 70%). This ensures your analytics accurately reflect what shoppers actually saw.

Q: My clickthrough events are being cancelled when a user navigates away. How do I fix this?

A: Because browsers often cancel requests during page transitions, you should use the keepalive: true flag in your fetch() options. This ensures the beacon reaches our server even after the user has left the page.

Q: I see 400 errors in my report even with the dev flag on. Is something wrong?

A: No, this is intended. 400 errors (Bad Requests) are always captured and surfaced in the Beacon Data Quality Report to help you resolve implementation hurdles during your build phase.

Q: Where do I find my siteId?

A: Your 6-character Site ID is located in the Athos Management Console (AMC). It is now a required part of the URL path for all Beacon 2.0 endpoints.

Q: What does a "Successful" response look like?

A: A successful beacon hit will return a 200 OK status with a JSON body of {"success": true}. This confirms that the data was received and validated by Athos’s analytics pipeline.

Q: I’m getting a 400 "Bad Request" error. What’s wrong?

A: This typically indicates a schema mismatch. Common culprits include:

• Missing Required Fields: Ensure all required fields are present. Review the required body parameters chart above for specific fields.
• Format Errors: Make sure that all required fields meet the format requirements. For example, check that your timestamp is in strict ISO 8601 format (e.g., 2024-05-20T14:30:00Z).
• Data Types: Ensure tag and responseId are strings, not integers or null.

Q: What should I check if I see a 404 "Invalid Path"?

A: Double-check your URL structure. The Beacon 2.0 URL is specific to your Site ID:
https://analytics.athoscommerce.net/beacon/v2/{siteId}/recommendations/render
Ensure {siteId} is replaced with your actual 6-character Athos Site ID located in your Athos Management Console.

Q: Why would I receive a 415 "Unsupported Media Type"?

A: This happens if the Content-Type header is missing or incorrect. The Beacon API requires:
'Content-Type': 'application/json' OR Content-Type': 'text/plain'

Q: When firing a render event my console shows a 413 "Payload Too Large." Is my event too big?

A: Render events are typically small. If you see this, check if you are accidentally nesting unnecessary data or large objects inside the context or data blocks.

Q: How do I handle a 500 "Internal Server Error"?

A: If you receive a 500 error, the issue may be on the Athos side. You should log the error and the messages array from the response, then contact Athos support with those details for investigation.

Q: Will IntelliSuggest continue to support shopper platform events?

A: Yes, IntelliSuggest will continue to monitor shopper behavior to ensure your search results remain optimized and your data insights stay accurate. However, it does not cover all of the new offerings in our Shopper Platform events, and will not be updated with new events moving forward. To stay on the most up-to-date infastructure we would suggest migrating to our new Shopper Platform Events.

Q: Is there a deadline to move off of IntelliSuggest?

A: There is no deadline or requirement to move. However, Intellisuggest is officially in maintenance mode. If you want access to our new endpoints and subsequent reports, we would suggest moving over to our Shopper Platform event structure.

Q: What happens if I choose not to move over to the new Shopping Platform events?

A: Your event tracking, product elevations, and reporting will continue to function without interruption. However, you will miss out on new events and reports associated with our new Shopper Platform Events.