The Beacon is the primary method by which Searchspring keeps track of events on your site. Sending your product recommendation events to the beacon is important to power the recommendations algorithm, as well as to power reporting (coming soon).
These instructions are for tracking recommendation events only. Please be sure to send this after calling the Personalized Recommendations API.
API Endpoint URL
https://beacon.searchspring.io/beacon
Request Parameters
Uses POST. Parameters cannot be passed in the URL. JSON objects are accepted.
The request must be passed as a JSON array of event objects. Multiple events may (and often should) be sent simultaneously.
Format |
String |
Description |
The type of recommendations interaction event being sent. |
Values |
For Profiles
- profile.render: A profile is loaded onto the page.
- profile.impression: A profile is visible to the shopper (within viewport, not hidden). If determining visibility is not possible, this can be sent at the same time as a profile.render event.
- profile.click: Any area of the profile is clicked.
For Recommended Products within a Profile
- profile.product.render: A recommended product is loaded onto the page.
- profile.product.impression: A recommended product is visible to the shopper (within viewport, not hidden). If determining visibility is not possible, this can be sent at the same time as a profile.product.render event.
- profile.product.click: A recommended product is clicked.
|
Format |
String |
Description |
You must pass "searchspring.recommendations.user-interactions" for all recommendation beacon requests. |
Value |
"searchspring.recommendations.user-interactions" |
Format |
String |
Description |
A randomly generated ID for the event. |
Example Value |
c1dbf50e-d9fd-427e-899e-ea2ce9e95620 |
Format |
String |
Description |
Parent Event ID. If there is a "parent" event that happened at the same time as this one, pass the parent's event ID here.
eg. If this event is profile.product.impression, pass the event ID for the profile.impression event that this event is tied to. |
Example Value |
c1dbf50e-d9fd-427e-899e-ea2ce9e95620 |
Format |
JSON Object |
Description |
Data that details the event. |
Format |
JSON Object |
Description |
For use with profile events. If passing a recommended product event specifically, skip to event.product below. |
Format |
String |
Description |
The general type of location that the profile is appearing on. |
Accepted Values |
basket-page, confirmation-page, product-page, no-results-page, home-page, other |
Format |
Integer |
Description |
The minimum product results threshold set within the profile. |
Example Value |
4 |
Format |
String |
Description |
The ID of the template version the profile is currently using. |
Example Value |
c98d2db2-2a71-48b1-a9c7-27bdfffa5d5e |
Format |
Array[JSON Objects] |
Description |
If on a Product Detail Page, pass the SKU of the product being viewed. If on a Cart/Basket page, pass every SKU in the cart. |
Example Value |
[{"sku": "123-ABC"},{"sku": "456-DEF"}] |
Format |
JSON Object |
Description |
For use with recommended product events. If passing an event for a profile, see event.profile above. |
Format |
String |
Description |
The recommended product's unique ID. May or may not be the same as SKU, depending on your store's data setup. |
Example Values |
4362364977221, ABC-123 |
Format |
JSON Object |
Description |
Details about the product. Pass the mappings object from the Personalized Recommendations API response. |
Example Value |
{"core": {"sku": "123-ABC", "name": "A Super Great Product", "url": "https://www.google.com", "thumbnailImageUrl": "http://placekitten.com/300/300", "price": 25.99, "msrp": 25.99 } }
|
Format |
Array[JSON Objects] |
Description |
If on a Product Detail Page, pass the SKU of the product being viewed. If on a Cart/Basket page, pass every SKU in the cart. |
Example Value |
[{"sku": "123-ABC"},{"sku": "456-DEF"}] |
Format |
JSON Object |
Description |
Contextual information about the recommendation event. |
Format |
String |
Description |
Should always be product-recommendation |
Example Value |
product-recommendation |
Format |
String |
Description |
The general type of location that the profile is appearing on. |
Accepted Values |
basket-page, confirmation-page, product-page, no-results-page, home-page, other |
Format |
JSON Object |
Description |
Data surrounding the context of the current shopper. |
Format |
String |
Description |
Your store's Site ID, which can be found on the My Account page. |
Example Value |
scmq7n |
Format |
String |
Description |
If the cookie "ssUserId" is currently set, use that.
If if doesn't exist yet, generate a new one with a UUID v4 generator in the language you are using (Such as these examples: JS, PHP, Node)
Be sure to set it as the cookie "ssUserId". This must be consistent with the "ssUserId" cookie that you're using for IntelliSuggest event tracking. |
Example Value |
"3022b347-a272-46c3-b676-62266e335a80" |
Format |
String |
Description |
If the cookie "ssSessionIdNamespace" is currently set, use that.
If if doesn't exist yet, generate a new one with a UUID v4 generator in the language you are using (Such as these examples: JS, PHP, Node)
Be sure to set it as the cookie "ssSessionIdNamespace" |
Example Value |
"6576ccfc-1294-4e30-878a-77cc2ca5299f" |
Format |
String |
Description |
Create a value for this using a UUID v4 generator in the language you are using (Such as these examples: JS, PHP, Node)
This value is not stored anywhere. |
Example Value |
"945ea9d2-f155-4cf1-81f5-f7c60b3ce0db" |
Example Request Payload
This example sends 2 events simultaneously: The profile impression and the impression of the product within it.
[
{
"type": "profile.impression",
"category": "searchspring.recommendations.user-interactions",
"id": "0f9fc1af-637c-4a5a-8270-0a1ecd0f4ffa",
"pid": null,
"event": {
"profile": {
"tag": "product-page",
"placement": "product-page",
"seed": [{"sku": "ABC-123"}]
},
"context": {
"type": "product-recommendation",
"tag": "product-page",
"placement": "product-page"
}
},
"context": {
"website": {"trackingCode": "scmq7n"},
"userId": "2bf5adfd-ae44-4ddc-88cb-0d7fa68e7a5c",
"sessionId": "d729b93a-9787-4fde-8fe9-56c8e7f9db67",
"pageLoadId": "f96052fe-4224-4585-b521-d292b262499b"
}
},
{
"type": "profile.product.impression",
"category": "searchspring.recommendations.user-interactions",
"id": "26ea1504-c79b-4350-8047-a92bd3f845ec",
"pid": "0f9fc1af-637c-4a5a-8270-0a1ecd0f4ffa",
"event": {
"product": {
"id": "4362364977221",
"seed": [{"sku": "ABC-123"}],
"mappings": {
"core": {
"sku": "DEF-456",
"name": "A Super Great Product",
"url": "http://www.google.com",
"thumbnailImageUrl": "http://placekitten.com/300/300",
"price": 25.99,
"msrp": 25.99
}
}
},
"context": {
"type": "product-recommendation",
"tag": "product-page",
"placement": "product-page"
}
},
"context": {
"website": {"trackingCode": "scmq7n"},
"userId": "2bf5adfd-ae44-4ddc-88cb-0d7fa68e7a5c",
"sessionId": "d729b93a-9787-4fde-8fe9-56c8e7f9db67",
"pageLoadId": "f96052fe-4224-4585-b521-d292b262499b"
}
}
]
Example Response
{
"success": true,
"results": {
"batch": [
{
"id": "2010f450-5a67-419d-af17-0706413cbadd",
"category": "searchspring.recommendations.user-interactions",
"type": "profile.impression"
}
]
}
}
Comments
0 comments
Article is closed for comments.