Skip to content

Commit

Permalink
Merge pull request #1314 from vtex/is-headless-updates
Browse files Browse the repository at this point in the history 
intelligent search events api (headless) - update descriptions and examples
  • Loading branch information
@julia-rabello
julia-rabello authored Sep 19, 2024
2 parents 1bfdaed + 348ed9d commit 577f7c4
Show file tree
Hide file tree
Showing 2 changed files with 35 additions and 80 deletions.
60 changes: 23 additions & 37 deletions PostmanCollections/VTEX - Intelligent Search Events API - Headless.json
View file
Original file line number Diff line number Diff line change
@@ -1,23 +1,23 @@
{
"_": {
"postman_id": "309092ed-7c43-4cb9-ba58-5081fb8fbc33"
"postman_id": "98c860ee-2779-4a3f-95c1-5bbaff19c696"
},
"item": [
{
"id": "6cc6f5ab-2a0e-47b4-b52a-f4ffe54e46f4",
"id": "e4f0e417-2665-403f-9695-110d8126032c",
"name": "Events",
"description": {
"content": "",
"type": "text/plain"
},
"item": [
{
"id": "6dc5ba04-11e5-4597-85ac-45d8a63238d3",
"id": "02fc4f7e-98aa-4b97-aceb-3e0becad8a96",
"name": "Save events",
"request": {
"name": "Save events",
"description": {
"content": "Creates search events to integrate with VTEX Intelligent Search using a headless implementation. \r\n\r\n >⚠️ **This API applies only to Headless scenarios**. It doesn't apply to stores using VTEX's storefront solution, natively integrated with Intelligent Search\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).",
"content": "Creates search events to integrate with VTEX Intelligent Search using a headless implementation. \r\n\r\nRead [VTEX Intelligent Search Events API - Headless - Overview](https://developers.vtex.com/docs/api-reference/intelligent-search-events-api-headless) for more information on event types and user identification.\r\n\r\n>⚠️ **This API applies only to Headless scenarios**. It doesn't apply to stores using VTEX's storefront solution, natively integrated with Intelligent Search\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).",
"type": "text/plain"
},
"url": {
Expand All @@ -32,11 +32,11 @@
{
"disabled": false,
"description": {
"content": "Name of the VTEX account. Used as part of the URL.",
"content": "(Required) Name of the VTEX account. Used as part of the URL.",
"type": "text/plain"
},
"type": "any",
"value": "{{accountName}}",
"value": "apiexamples",
"key": "accountName"
}
]
Expand All @@ -50,9 +50,10 @@
"method": "POST",
"body": {
"mode": "raw",
"raw": "{\n \"session\": \"zZlNhqz1vFJP6iPG5Oqtt\",\n \"anonymous\": \"Om1TNluGvgmSgU5OOTvkkd\",\n \"url\": \"https://example.com/search/?query=zapatilha\",\n \"agent\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0\",\n \"type\": \"search.query\",\n \"text\": \"zapatilha\",\n \"misspelled\": true,\n \"match\": 392,\n \"operator\": \"and\"\n}",
"raw": "{\n \"session\": \"df66a4d239864d2e8497c89aea14a3ad\",\n \"anonymous\": \"eed429ecf04a4a23ae7f4429033b48cd\",\n \"url\": \"https://example.com/search/?query=zapatilha\",\n \"agent\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0\",\n \"type\": \"search.query\",\n \"text\": \"zapatilha\",\n \"misspelled\": true,\n \"match\": 392,\n \"operator\": \"and\"\n}",
"options": {
"raw": {
"headerFamily": "json",
"language": "json"
}
}
Expand All @@ -63,7 +64,7 @@
"_": {
"postman_previewlanguage": "text"
},
"id": "3f5b2a2d-9206-4cea-8476-0d9758919b0a",
"id": "b7657979-ba01-4e44-8ee6-4d813a1f642c",
"name": "No content",
"originalRequest": {
"url": {
Expand All @@ -74,47 +75,37 @@
"{{baseUrl}}"
],
"query": [],
"variable": [
{
"disabled": false,
"description": {
"content": "Name of the VTEX account. Used as part of the URL.",
"type": "text/plain"
},
"type": "any",
"value": "{{accountName}}",
"key": "accountName"
}
]
"variable": []
},
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"method": "POST",
"body": {
"mode": "raw",
"raw": "{\n \"session\": \"zZlNhqz1vFJP6iPG5Oqtt\",\n \"anonymous\": \"Om1TNluGvgmSgU5OOTvkkd\",\n \"url\": \"https://example.com/search/?query=zapatilha\",\n \"agent\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0\",\n \"type\": \"search.query\",\n \"text\": \"zapatilha\",\n \"misspelled\": true,\n \"match\": 392,\n \"operator\": \"and\"\n}",
"raw": "{\n \"session\": \"df66a4d239864d2e8497c89aea14a3ad\",\n \"anonymous\": \"eed429ecf04a4a23ae7f4429033b48cd\",\n \"url\": \"https://example.com/search/?query=zapatilha\",\n \"agent\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0\",\n \"type\": \"search.query\",\n \"text\": \"zapatilha\",\n \"misspelled\": true,\n \"match\": 392,\n \"operator\": \"and\"\n}",
"options": {
"raw": {
"headerFamily": "json",
"language": "json"
}
}
}
},
"status": "No Content",
"code": 204,
"header": [
{
"key": "Content-Type",
"value": "text/plain"
}
],
"body": "",
"header": [],
"cookie": []
}
],
"event": [
{
"listen": "test",
"script": {
"id": "4ec76ece-0e32-49ed-9f31-12196a7d3f57",
"id": "67cbcde2-6263-4d3d-a991-15472a689805",
"type": "text/javascript",
"exec": [
"// Validate status 2xx \npm.test(\"[POST]::/event - Status code is 2xx\", function () {\n pm.response.to.be.success;\n});\n",
Expand All @@ -134,27 +125,22 @@
"event": [],
"variable": [
{
"description": {
"content": "Name of the VTEX account. Used as part of the URL.",
"type": "text/plain"
},
"type": "any",
"value": "apiexamples",
"key": "accountName"
},
{
"type": "string",
"type": "any",
"value": "https://sp.vtex.com/event-api/v1/{{accountName}}",
"key": "baseUrl"
}
],
"info": {
"_postman_id": "309092ed-7c43-4cb9-ba58-5081fb8fbc33",
"_postman_id": "98c860ee-2779-4a3f-95c1-5bbaff19c696",
"name": "VTEX Intelligent Search Events API - Headless",
"version": {},
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
"description": {
"content": "Intelligent Search Events API is responsible for collecting the search events to improve your search results, such as page interactions and conversion, in a headless implementation. Some of the features improved by this collection are the possibility to sort the products by clicks or record the top search in the autocomplete.\r\n\r\n>⚠️ **This API applies only to Headless scenarios**. It doesn't apply to stores using Store Framework, since they are already integrated with all Intelligent Search features.\r\n\r\n## Building the request body\r\n\r\nIn the following sections, we detail the required structure for the request body of the `POST`[Save events](https://developers.vtex.com/docs/api-reference/intelligent-search-events-api-headless#post-/event) endpoint.\r\n\r\n### User identification\r\n\r\nTo identify the user, there are two required identifiers according to the [nanoid](https://github.com/ai/nanoid) pattern: `session` and `anonymous`. Read the API reference for more information on each field.\r\n\r\n> ⚠️ The `session` and `anonymous` identifiers need to be sent in every request.\r\n\r\n### Event type\r\n\r\nTo identify the events that occur in our search, the `type` field is required in the request. The most common event types are the following:\r\n\r\n| Event type | Value | Description |\r\n| - | - | - |\r\n| Session Ping | `session.ping` | Sends an ACK to the API to renew the session server-side. It should be sent every 1 minute. |\r\n| Page Cart | `page.cart` | Sends an event every time the shopper enters the cart page. Each interaction should include all products inside the shopping cart at that time. In case a product is removed, sent the updated card. |\r\n| Empty Cart | `page.empty_cart` | Sends an event if there are no products in the shopping cart at that time. | \r\n| Page Confirmation |`page.confirmation` | Sends a confirmation informing the products that were bought. |\r\n| Search Click | `search.click` | Sends an event every time a shopper clicks on a product from a search page. |\r\n| Search Query | `search.query` | Sends a query event every time the shopper makes a full-text search. |\r\n\r\n### Finding search query information\r\n\r\nSearch query information is possible to find in the Intelligent Search GraphQL response. To retrieve the information above, add operator, fuzzy, and correction attributes in the GraphQL query. Example:\r\n\r\n```graphql\r\nquery {\r\n productSearch(fullText: \"id:43534\") {\r\n products {\r\n productId\r\n productName\r\n ...\r\n }\r\n operator\r\n fuzzy\r\n correction{ \r\n misspelled\r\n }\r\n }\r\n}\r\n```\r\n\r\n### Optional fields\r\n\r\nInformation to identify where the context of that request came from: `agent` and `URL`. Read the API reference for more information on each field.\r\n\r\n### Request body examples\r\n\r\nThe body is built by combining the user information, the event type, and add the optional fields. Below there is an example for each type of event.\r\n\r\n#### Session Ping\r\n\r\n```json\r\n{\r\n\t\"session\":\"zZlNhqz1vFJP6iPG5Oqdf\",\r\n\t\"anonymous\":\"Om1TNluGvgmSgU5OOTvdfg\",\r\n\t\"url\":\"https://example.com/search/?query=zapatilha\",\r\n\t\"agent\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0\",\r\n\t\"type\":\"session.ping\"\r\n}\r\n``` \r\n\r\n#### Page Cart \r\n\r\n```json\r\n{\r\n \"session\":\"zZlNhqz1vFJP6iPG5Oqtt\",\r\n \"anonymous\":\"Om1TNluGvgmSgU5OOTvkkd\",\r\n \"products\": [\r\n {\r\n \"productId\": \"ABC123\",\r\n \"quantity\": 2\r\n },\r\n {\r\n \"productId\": \"XYZ789\",\r\n \"quantity\": 1\r\n }\r\n ],\r\n \"type\": \"page.cart\"\r\n}\r\n```\r\n\r\n#### Empty Cart \r\n\r\n```json\r\n{\r\n \"session\":\"zZlNhqz1vFJP6iPG5Oqtt\",\r\n \"anonymous\":\"Om1TNluGvgmSgU5OOTvkkd\",\r\n \"products\": [],\r\n \"type\": \"page.empty_cart\"\r\n}\r\n```\r\n\r\n#### Page Confirmation\r\n\r\n```json\r\n{\r\n \"session\":\"zZlNhqz1vFJP6iPG5Oqtt\",\r\n \"anonymous\":\"Om1TNluGvgmSgU5OOTvkkd\",\r\n \"products\": [\r\n {\r\n \"productId\": \"ABC123\",\r\n \"price\": 9.99,\r\n \"quantity\": 3\r\n },\r\n {\r\n \"productId\": \"XYZ789\",\r\n \"price\": 5.99,\r\n \"quantity\": 2\r\n }\r\n ],\r\n \"order\": \"123ABC\",\r\n \"type\": \"page.confirmation\"\r\n}\r\n```\r\n\r\n#### Search Click\r\n\r\n```json\r\n{\r\n\t\"type\": \"search.click\",\r\n\t\"productId\": \"12345\",\r\n\t\"position\": 1,\r\n\t\"url\": \"https://example.com/s?q=pneu&sort=score_desc&page=0\",\r\n\t\"text\": \"pneu\",\r\n\t\"agent\": \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36\",\r\n\t\"anonymous\": \"1ce47e50-3f10-4556-95d3-57d4881c03a4\",\r\n\t\"session\": \"51a53ce3-096d-4740-a6d0-3cf86085ba13\"\r\n}\r\n```\r\n\r\n#### Search Query\r\n\r\n```json\r\n{\r\n\t\"session\":\"zZlNhqz1vFJP6iPG5Oqtt\",\r\n\t\"anonymous\":\"Om1TNluGvgmSgU5OOTvkkd\",\r\n\t\"url\":\"https://example.com/search/?query=zapatilha\",\r\n\t\"agent\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0\",\r\n\t\"type\":\"search.query\",\r\n\t\"text\":\"zapatilha\",\r\n\t\"misspelled\":true,\r\n\t\"match\":392,\r\n\t\"operator\":\"and\"\r\n}\r\n```\r\n",
"content": "Intelligent Search Events API is responsible for collecting the search events to improve your search results, such as page interactions and conversion, in a headless implementation. Some of the features improved by this collection are the possibility to sort the products by clicks or record the top search in the autocomplete.\r\n\r\n>⚠️ **This API applies only to Headless scenarios**. It doesn't apply to stores using Store Framework, since they are already integrated with all Intelligent Search features.\r\n\r\n## Building the request body\r\n\r\nIn the following sections, we explain the required structure for the request body for saving events. Check the `POST` [Save events](https://developers.vtex.com/docs/api-reference/intelligent-search-events-api-headless#post-/event) endpoint reference for more detailed field descriptions and examples.\r\n\r\nFull request example (Session Ping):\r\n\r\n```json\r\ncurl --request post \\\r\n\t--url https://sp.vtex.com/event-api/v1/{accountName}/event \\\r\n\t--header 'Content-Type: application/json' \\\r\n\t--data '{\"session\":\"df66a4d239864d2e8497c89aea14a3ad\",\"anonymous\":\"eed429ecf04a4a23ae7f4429033b48cd\",\"url\":\"https://example.com/search/?query=zapatilha\",\"agent\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0\",\"type\":\"search.query\",\"text\":\"zapatilha\",\"misspelled\":true,\"match\":392,\"operator\":\"and\"}'\r\n```\r\n\r\n### User identification\r\n\r\nTo identify the user, there are two required identifiers: `session` and `anonymous`. We recommend using a [Universally Unique Identifier (UUID) v4](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID) without dashes.\r\n\r\nSample JavaScript code to generate a random UUID without dashes:\r\n\r\n```js\r\nwindow.crypto.randomUUID().replaceAll('-', '')\r\n```\r\n\r\n>⚠️ The `session` and `anonymous` identifiers need to be sent in every request.\r\n\r\n\r\n### Event type\r\n\r\nTo identify the events that occur in our search, the `type` field is required in the request. The most common event types are the following:\r\n\r\n| Event type | Value | Description |\r\n| - | - | - |\r\n| Session Ping | `session.ping` | Sends an ACK to the API to renew the session server-side. It should be sent every 1 minute. |\r\n| Page Confirmation |`page.confirmation` | Sends a confirmation informing the products that were bought. |\r\n| Search Click | `search.click` | Sends an event every time a shopper clicks on a product from a search page. |\r\n| Search Query | `search.query` | Sends a query event every time the shopper makes a full-text search. |\r\n\r\n### Optional fields\r\n\r\nInformation to identify where the context of that request came from: `agent` and `URL`. Read the API reference for more information on each field.\r\n\r\n### Request body examples per event type\r\n\r\nThe body is built by combining the user information, the event type, and add the optional fields. Below there is an example for each type of event.\r\n\r\n#### Session Ping\r\n\r\n\r\n```json\r\n{\r\n\t\"session\":\"df66a4d239864d2e8497c89aea14a3ad\",\r\n\t\"anonymous\":\"eed429ecf04a4a23ae7f4429033b48cd\",\r\n\t\"url\":\"https://example.com/search/?query=zapatilha\",\r\n\t\"agent\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0\",\r\n\t\"type\":\"session.ping\"\r\n}\r\n```\r\n\r\n#### Page Confirmation\r\n\r\n```json\r\n{\r\n \"session\":\"df66a4d239864d2e8497c89aea14a3ad\",\r\n \"anonymous\":\"eed429ecf04a4a23ae7f4429033b48cd\",\r\n \"products\": [\r\n {\r\n \"productId\": \"ABC123\",\r\n \"price\": 9.99,\r\n \"quantity\": 3\r\n },\r\n {\r\n \"productId\": \"XYZ789\",\r\n \"price\": 5.99,\r\n \"quantity\": 2\r\n }\r\n ],\r\n \"order\": \"123ABC\",\r\n \"type\": \"page.confirmation\"\r\n}\r\n```\r\n\r\n#### Search Click\r\n\r\n```json\r\n{\r\n\t\"type\": \"search.click\",\r\n\t\"productId\": \"12345\",\r\n\t\"position\": 1,\r\n\t\"url\": \"https://example.com/s?q=pneu&sort=score_desc&page=0\",\r\n\t\"text\": \"pneu\",\r\n\t\"agent\": \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36\",\r\n\t\"anonymous\": \"1ce47e50-3f10-4556-95d3-57d4881c03a4\",\r\n\t\"session\": \"51a53ce3-096d-4740-a6d0-3cf86085ba13\"\r\n}\r\n```\r\n\r\n#### Search Query\r\n\r\n```json\r\n{\r\n\t\"session\":\"df66a4d239864d2e8497c89aea14a3ad\",\r\n\t\"anonymous\":\"eed429ecf04a4a23ae7f4429033b48cd\",\r\n\t\"url\":\"https://example.com/search/?query=zapatilha\",\r\n\t\"agent\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:83.0) Gecko/20100101 Firefox/83.0\",\r\n\t\"type\":\"search.query\",\r\n\t\"text\":\"zapatilha\",\r\n\t\"misspelled\":true,\r\n\t\"match\":392,\r\n\t\"operator\":\"and\"\r\n}\r\n```\r\n\r\n### Finding search query information\r\n\r\nSearch query information is possible to find in the Intelligent Search GraphQL response. To retrieve the information above, add operator, fuzzy, and correction attributes in the GraphQL query. Example:\r\n\r\n```graphql\r\nquery {\r\n productSearch(fullText: \"id:43534\") {\r\n products {\r\n productId\r\n productName\r\n ...\r\n }\r\n operator\r\n fuzzy\r\n correction{ \r\n misspelled\r\n }\r\n }\r\n}\r\n```",
"type": "text/plain"
}
}
Expand Down
Loading

0 comments on commit 577f7c4

Please sign in to comment.