From b703dea4a81cc27e892e7adc99870dc1e0f369d1 Mon Sep 17 00:00:00 2001 From: Kai Welke Date: Thu, 22 Jun 2023 16:55:32 +0200 Subject: [PATCH] docs(specs): review Insights API spec (#1647) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: gazconroy Co-authored-by: Clément Vannicatte Co-authored-by: Mouaad Aallam --- .github/.cache_version | 2 +- .../client_insights/example/insights.dart | 9 +- specs/insights/common/schemas/ClickEvent.yml | 2 + .../common/schemas/ClickedFilters.yml | 23 ++ .../common/schemas/ClickedObjectIDs.yml | 27 ++ .../schemas/ClickedObjectIDsAfterSearch.yml | 34 ++ .../common/schemas/ConversionEvent.yml | 2 + .../common/schemas/ConvertedFilters.yml | 22 ++ .../common/schemas/ConvertedObjectIDs.yml | 27 ++ .../schemas/ConvertedObjectIDsAfterSearch.yml | 32 ++ .../common/schemas/EventAttributes.yml | 83 +++++ specs/insights/common/schemas/EventsItems.yml | 9 + .../common/schemas/EventsResponse.yml | 10 + specs/insights/common/schemas/ViewEvent.yml | 2 + .../insights/common/schemas/ViewedFilters.yml | 26 ++ .../common/schemas/ViewedObjectIDs.yml | 23 ++ specs/insights/paths/pushEvents.yml | 314 +++++++++++++----- specs/insights/spec.yml | 10 +- .../methods/requests/insights/pushEvents.json | 46 --- 19 files changed, 572 insertions(+), 131 deletions(-) create mode 100644 specs/insights/common/schemas/ClickEvent.yml create mode 100644 specs/insights/common/schemas/ClickedFilters.yml create mode 100644 specs/insights/common/schemas/ClickedObjectIDs.yml create mode 100644 specs/insights/common/schemas/ClickedObjectIDsAfterSearch.yml create mode 100644 specs/insights/common/schemas/ConversionEvent.yml create mode 100644 specs/insights/common/schemas/ConvertedFilters.yml create mode 100644 specs/insights/common/schemas/ConvertedObjectIDs.yml create mode 100644 specs/insights/common/schemas/ConvertedObjectIDsAfterSearch.yml create mode 100644 specs/insights/common/schemas/EventAttributes.yml create mode 100644 specs/insights/common/schemas/EventsItems.yml create mode 100644 specs/insights/common/schemas/EventsResponse.yml create mode 100644 specs/insights/common/schemas/ViewEvent.yml create mode 100644 specs/insights/common/schemas/ViewedFilters.yml create mode 100644 specs/insights/common/schemas/ViewedObjectIDs.yml diff --git a/.github/.cache_version b/.github/.cache_version index 369bd4c2a4..d788d43357 100644 --- a/.github/.cache_version +++ b/.github/.cache_version @@ -1 +1 @@ -0.0.29 +0.0.31 diff --git a/clients/algoliasearch-client-dart/packages/client_insights/example/insights.dart b/clients/algoliasearch-client-dart/packages/client_insights/example/insights.dart index 602cf7141e..79a1d6b74f 100644 --- a/clients/algoliasearch-client-dart/packages/client_insights/example/insights.dart +++ b/clients/algoliasearch-client-dart/packages/client_insights/example/insights.dart @@ -9,19 +9,18 @@ void main() async { // Creating an InsightEvents object with a list of InsightEvent objects. // Each InsightEvent represents an event such as a user viewing a specific item. - final events = InsightEvents( + final events = InsightsEvents( events: [ - InsightEvent( - eventType: EventType.view, + ViewedObjectIDs( + eventType: ViewEvent.view, eventName: 'View event', index: 'instant_search', userToken: 'anonymous', - queryID: '43b15df305339e827f0ac0bdc5ebcaa7', objectIDs: ['5477500'], ) ], ); - await insights.pushEvents(insightEvents: events); + await insights.pushEvents(insightsEvents: events); // Close the client and dispose of all underlying resources. insights.dispose(); diff --git a/specs/insights/common/schemas/ClickEvent.yml b/specs/insights/common/schemas/ClickEvent.yml new file mode 100644 index 0000000000..c4f30c9da9 --- /dev/null +++ b/specs/insights/common/schemas/ClickEvent.yml @@ -0,0 +1,2 @@ +type: string +enum: [click] diff --git a/specs/insights/common/schemas/ClickedFilters.yml b/specs/insights/common/schemas/ClickedFilters.yml new file mode 100644 index 0000000000..1971ea1190 --- /dev/null +++ b/specs/insights/common/schemas/ClickedFilters.yml @@ -0,0 +1,23 @@ +type: object +title: Clicked filters +description: Use this event to track when users click facet filters in your user interface. +additionalProperties: false +properties: + eventName: + $ref: './EventAttributes.yml#/eventName' + eventType: + $ref: './ClickEvent.yml' + index: + $ref: './EventAttributes.yml#/index' + filters: + $ref: './EventAttributes.yml#/filters' + userToken: + $ref: './EventAttributes.yml#/userToken' + timestamp: + $ref: './EventAttributes.yml#/timestamp' +required: + - eventName + - eventType + - index + - filters + - userToken diff --git a/specs/insights/common/schemas/ClickedObjectIDs.yml b/specs/insights/common/schemas/ClickedObjectIDs.yml new file mode 100644 index 0000000000..75cf40325d --- /dev/null +++ b/specs/insights/common/schemas/ClickedObjectIDs.yml @@ -0,0 +1,27 @@ +type: object +title: Clicked object IDs +description: | + Use this event to track when users click items unrelated to a previous Algolia request. + For example, if you don't use Algolia to build your category pages, use this event. + + To track click events related to Algolia requests, use the "Clicked object IDs after search" event. +additionalProperties: false +properties: + eventName: + $ref: './EventAttributes.yml#/eventName' + eventType: + $ref: './ClickEvent.yml' + index: + $ref: './EventAttributes.yml#/index' + objectIDs: + $ref: './EventAttributes.yml#/objectIDs' + userToken: + $ref: './EventAttributes.yml#/userToken' + timestamp: + $ref: './EventAttributes.yml#/timestamp' +required: + - eventName + - eventType + - index + - objectIDs + - userToken diff --git a/specs/insights/common/schemas/ClickedObjectIDsAfterSearch.yml b/specs/insights/common/schemas/ClickedObjectIDsAfterSearch.yml new file mode 100644 index 0000000000..bc7fa4a75e --- /dev/null +++ b/specs/insights/common/schemas/ClickedObjectIDsAfterSearch.yml @@ -0,0 +1,34 @@ +type: object +title: Clicked object IDs after search +description: | + Click event after an Algolia request. + + Use this event to track when users click items in the search results. + If you're building your category pages with Algolia, + you'll also use this event. +additionalProperties: false +properties: + eventName: + $ref: './EventAttributes.yml#/eventName' + eventType: + $ref: './ClickEvent.yml' + index: + $ref: './EventAttributes.yml#/index' + objectIDs: + $ref: './EventAttributes.yml#/objectIDs' + positions: + $ref: './EventAttributes.yml#/positions' + queryID: + $ref: './EventAttributes.yml#/queryID' + userToken: + $ref: './EventAttributes.yml#/userToken' + timestamp: + $ref: './EventAttributes.yml#/timestamp' +required: + - eventName + - eventType + - index + - objectIDs + - positions + - queryID + - userToken diff --git a/specs/insights/common/schemas/ConversionEvent.yml b/specs/insights/common/schemas/ConversionEvent.yml new file mode 100644 index 0000000000..88a20ad90a --- /dev/null +++ b/specs/insights/common/schemas/ConversionEvent.yml @@ -0,0 +1,2 @@ +type: string +enum: [conversion] diff --git a/specs/insights/common/schemas/ConvertedFilters.yml b/specs/insights/common/schemas/ConvertedFilters.yml new file mode 100644 index 0000000000..9ae8fd2cc7 --- /dev/null +++ b/specs/insights/common/schemas/ConvertedFilters.yml @@ -0,0 +1,22 @@ +type: object +title: Converted filters +additionalProperties: false +properties: + eventName: + $ref: './EventAttributes.yml#/eventName' + eventType: + $ref: './ConversionEvent.yml' + index: + $ref: './EventAttributes.yml#/index' + filters: + $ref: './EventAttributes.yml#/filters' + userToken: + $ref: './EventAttributes.yml#/userToken' + timestamp: + $ref: './EventAttributes.yml#/timestamp' +required: + - eventName + - eventType + - index + - filters + - userToken diff --git a/specs/insights/common/schemas/ConvertedObjectIDs.yml b/specs/insights/common/schemas/ConvertedObjectIDs.yml new file mode 100644 index 0000000000..6bf0902bb4 --- /dev/null +++ b/specs/insights/common/schemas/ConvertedObjectIDs.yml @@ -0,0 +1,27 @@ +type: object +title: Converted object IDs +description: | + Use this event to track when users convert on items unrelated to a previous Algolia request. + For example, if you don't use Algolia to build your category pages, use this event. + + To track conversion events related to Algolia requests, use the "Converted object IDs after search" event. +additionalProperties: false +properties: + eventName: + $ref: './EventAttributes.yml#/eventName' + eventType: + $ref: './ConversionEvent.yml' + index: + $ref: './EventAttributes.yml#/index' + objectIDs: + $ref: './EventAttributes.yml#/objectIDs' + userToken: + $ref: './EventAttributes.yml#/userToken' + timestamp: + $ref: './EventAttributes.yml#/timestamp' +required: + - eventName + - eventType + - index + - objectIDs + - userToken diff --git a/specs/insights/common/schemas/ConvertedObjectIDsAfterSearch.yml b/specs/insights/common/schemas/ConvertedObjectIDsAfterSearch.yml new file mode 100644 index 0000000000..2231b00614 --- /dev/null +++ b/specs/insights/common/schemas/ConvertedObjectIDsAfterSearch.yml @@ -0,0 +1,32 @@ +type: object +title: Converted object IDs after search +description: | + Use this event to track when users convert after a previous Algolia request. + For example, a user clicks on an item in the search results to view the product detail page. + Then, the user adds the item to their shopping cart. + + If you're building your category pages with Algolia, + you'll also use this event. +additionalProperties: false +properties: + eventName: + $ref: './EventAttributes.yml#/eventName' + eventType: + $ref: './ConversionEvent.yml' + index: + $ref: './EventAttributes.yml#/index' + objectIDs: + $ref: './EventAttributes.yml#/objectIDs' + queryID: + $ref: './EventAttributes.yml#/queryID' + userToken: + $ref: './EventAttributes.yml#/userToken' + timestamp: + $ref: './EventAttributes.yml#/timestamp' +required: + - eventName + - eventType + - index + - objectIDs + - queryID + - userToken diff --git a/specs/insights/common/schemas/EventAttributes.yml b/specs/insights/common/schemas/EventAttributes.yml new file mode 100644 index 0000000000..b4c83c07af --- /dev/null +++ b/specs/insights/common/schemas/EventAttributes.yml @@ -0,0 +1,83 @@ +eventName: + type: string + minLength: 1 + maxLength: 64 + description: | + Can contain up to 64 ASCII characters. + + Consider naming events consistently—for example, + by adopting Segment's + [object-action](https://segment.com/academy/collecting-data/naming-conventions-for-clean-data/#the-object-action-framework) + framework. + example: Product Clicked + +index: + type: string + description: Name of the Algolia index. + example: YourIndexName + +userToken: + type: string + minLength: 1 + maxLength: 128 + pattern: '[a-zA-Z0-9_=/+-]{1,128}' + description: | + Anonymous or pseudonymous user identifier. + + > **Note**: Never include personally identifiable information in user tokens. + example: test-user-1 + +timestamp: + type: integer + format: int64 + description: | + Time of the event in milliseconds in [Unix epoch time](https://wikipedia.org/wiki/Unix_time). + By default, the Insights API uses the time it receives an event as its timestamp. + example: 1687193127 + +queryID: + type: string + pattern: '[0-9a-f]{32}' + minLength: 32 + maxLength: 32 + description: | + Unique identifier for a search query. + + The query ID is required for events related to search or browse requests. + If you add `clickAnalytics: true` as a search request parameter, the query ID is included in the API response. + example: 3e48cd0616e466948dd85abf5c3fbbe2 + +objectIDs: + type: array + description: List of object identifiers for items of an Algolia index. + items: + type: string + minItems: 1 + maxItems: 20 + example: ['object-1', 'object-2', 'object-3'] + +filters: + type: array + description: | + Facet filters. + + Each facet filter string must be URL-encoded, such as, `discount:10%25`. + items: + type: string + minItems: 1 + maxItems: 20 + example: ['brand:apple'] + +positions: + type: array + items: + type: integer + minimum: 1 + minItems: 1 + maxItems: 20 + description: | + Position of the clicked objects in the search results. + + The first search result has a position of 1 (not 0). + You must provide 1 `position` for each `objectID`. + example: [1, 2, 5] diff --git a/specs/insights/common/schemas/EventsItems.yml b/specs/insights/common/schemas/EventsItems.yml new file mode 100644 index 0000000000..2d124379d4 --- /dev/null +++ b/specs/insights/common/schemas/EventsItems.yml @@ -0,0 +1,9 @@ +oneOf: + - $ref: './ClickedObjectIDsAfterSearch.yml' + - $ref: './ConvertedObjectIDsAfterSearch.yml' + - $ref: './ClickedObjectIDs.yml' + - $ref: './ConvertedObjectIDs.yml' + - $ref: './ClickedFilters.yml' + - $ref: './ConvertedFilters.yml' + - $ref: './ViewedObjectIDs.yml' + - $ref: './ViewedFilters.yml' diff --git a/specs/insights/common/schemas/EventsResponse.yml b/specs/insights/common/schemas/EventsResponse.yml new file mode 100644 index 0000000000..2c0e9d2e71 --- /dev/null +++ b/specs/insights/common/schemas/EventsResponse.yml @@ -0,0 +1,10 @@ +type: object +description: The response of the Insights API. +additionalProperties: false +properties: + message: + type: string + description: Details about the response, such as error messages. + status: + type: integer + description: The HTTP status code of the response. diff --git a/specs/insights/common/schemas/ViewEvent.yml b/specs/insights/common/schemas/ViewEvent.yml new file mode 100644 index 0000000000..3dcd3bf787 --- /dev/null +++ b/specs/insights/common/schemas/ViewEvent.yml @@ -0,0 +1,2 @@ +type: string +enum: [view] diff --git a/specs/insights/common/schemas/ViewedFilters.yml b/specs/insights/common/schemas/ViewedFilters.yml new file mode 100644 index 0000000000..dd80426a82 --- /dev/null +++ b/specs/insights/common/schemas/ViewedFilters.yml @@ -0,0 +1,26 @@ +type: object +title: Viewed filters +description: | + Use this method to capture active filters. + For example, when browsing a category page, + users see content filtered on that specific category. +additionalProperties: false +properties: + eventName: + $ref: './EventAttributes.yml#/eventName' + eventType: + $ref: './ViewEvent.yml' + index: + $ref: './EventAttributes.yml#/index' + filters: + $ref: './EventAttributes.yml#/filters' + userToken: + $ref: './EventAttributes.yml#/userToken' + timestamp: + $ref: './EventAttributes.yml#/timestamp' +required: + - eventName + - eventType + - index + - filters + - userToken diff --git a/specs/insights/common/schemas/ViewedObjectIDs.yml b/specs/insights/common/schemas/ViewedObjectIDs.yml new file mode 100644 index 0000000000..a81103eead --- /dev/null +++ b/specs/insights/common/schemas/ViewedObjectIDs.yml @@ -0,0 +1,23 @@ +type: object +title: Viewed object IDs +description: Use this event to track when users viewed items in the search results. +additionalProperties: false +properties: + eventName: + $ref: './EventAttributes.yml#/eventName' + eventType: + $ref: './ViewEvent.yml' + index: + $ref: './EventAttributes.yml#/index' + objectIDs: + $ref: './EventAttributes.yml#/objectIDs' + userToken: + $ref: './EventAttributes.yml#/userToken' + timestamp: + $ref: './EventAttributes.yml#/timestamp' +required: + - eventName + - eventType + - index + - objectIDs + - userToken diff --git a/specs/insights/paths/pushEvents.yml b/specs/insights/paths/pushEvents.yml index 26ac6ad080..16e445106e 100644 --- a/specs/insights/paths/pushEvents.yml +++ b/specs/insights/paths/pushEvents.yml @@ -2,105 +2,265 @@ post: tags: - events operationId: pushEvents - summary: Push events. + summary: Send events. description: | - This command pushes an array of events. + Send a list of events to the Insights API. - An event is - - an action: `eventName` - - performed in a context: `eventType` - - at some point in time provided: `timestamp` - - by an end user: `userToken` - - on something: `index` - - - Notes: - - To be accepted, all events sent must be valid. - - The size of the body must be *less than 2 MB*. - - When an event is tied to an Algolia search, it must also provide a `queryID`. If that event is a `click`, their absolute `positions` should also be passed. - - We consider that an `index` provides access to 2 resources: objects and filters. An event can only interact with a single resource type, but not necessarily on a single item. As such an event will accept an array of `objectIDs` or `filters`. + You can include up to 1,000 events in a single request, + but the request body must be smaller than 2 MB. requestBody: required: true content: application/json: schema: - title: InsightEvents + title: InsightsEvents type: object - description: Object containing the events sent. additionalProperties: false required: - events properties: events: type: array - description: Array of events sent. + description: | + List of click and conversion events. + + An event is an object representing a user interaction. + Events have attributes that describe the interaction, + such as an event name, a type, or a user token. + Some attributes require other attributes to be declared, + and some attributes can't be declared at the same time. + + **All** events must be valid, otherwise the API returns an error. + minItems: 1 + maxItems: 1000 items: - title: InsightEvent - type: object - description: Insights event. - additionalProperties: false - maximum: 1000 - properties: - eventType: - $ref: '../common/enums.yml#/eventType' - eventName: - type: string - maximum: 64 - description: A user-defined string used to categorize events. - index: - type: string - description: Name of the targeted index. - userToken: - type: string - pattern: '[a-zA-Z0-9_-=/+]{1,128}' - description: A user identifier. Depending if the user is logged-in or not, several strategies can be used from a sessionId to a technical identifier. You should always send pseudonymous or anonymous userTokens. - timestamp: - type: integer - format: int64 - description: Time of the event expressed in milliseconds since the Unix epoch. - queryID: - type: string - description: Algolia queryID. This is required when an event is tied to a search. - objectIDs: - type: array - description: An array of index objectID. Limited to 20 objects. An event can’t have both objectIDs and filters at the same time. - items: - type: string - filters: - type: array - description: An array of filters. Limited to 10 filters. An event can’t have both objectIDs and filters at the same time. - items: - type: string - positions: - type: array - description: Position of the click in the list of Algolia search results. This field is required if a queryID is provided. One position must be provided for each objectID. - items: - type: integer - required: - - eventType - - eventName - - index - - userToken + $ref: '../common/schemas/EventsItems.yml' + examples: + ClickObjectIDsAfterSearch: + summary: Click event after search requests. + value: + 'events': + - 'eventName': 'Products Clicked' + 'eventType': 'click' + 'index': 'test-index' + 'userToken': 'test-user-1' + 'objectIDs': ['object-1'] + 'positions': [1] + 'queryID': '7dfe2ada7bca48bdd0629649df0bee07' + ConversionObjectIDsAfterSearch: + summary: Conversion event after search requests. + value: + 'events': + - 'eventName': 'Products Added To Cart' + 'eventType': 'conversion' + 'index': 'test-index' + 'userToken': 'test-user-1' + 'objectIDs': ['object-1'] + 'queryID': '7dfe2ada7bca48bdd0629649df0bee07' + ClickObjectIDs: + summary: Click event. + value: + 'events': + - 'eventName': 'Products Clicked' + 'eventType': 'click' + 'index': 'test-index' + 'userToken': 'test-user-1' + 'objectIDs': ['object-1'] + ConversionObjectIDs: + summary: Conversion event. + value: + 'events': + - 'eventName': 'Products Added To Cart' + 'eventType': 'conversion' + 'index': 'test-index' + 'userToken': 'test-user-1' + 'objectIDs': ['object-1'] + ClickFilter: + summary: Click event with filters. + value: + 'events': + - 'eventName': 'Category Clicked' + 'eventType': 'click' + 'index': 'test-index' + 'userToken': 'test-user-1' + 'filters': ['category:books'] + ConversionFilter: + summary: Conversion event with filters. + value: + 'events': + - 'eventName': 'Category Converted' + 'eventType': 'conversion' + 'index': 'test-index' + 'userToken': 'test-user-1' + 'filters': ['category:books'] + ViewObjectIDs: + summary: View event. + value: + 'events': + - 'eventName': 'Products Viewed' + 'eventType': 'view' + 'index': 'test-index' + 'userToken': 'test-user-1' + 'objectIDs': ['object-1'] + ViewFilters: + summary: View event with filters. + value: + 'events': + - 'eventName': 'Category Viewed' + 'eventType': 'view' + 'index': 'test-index' + 'userToken': 'test-user-1' + 'filters': ['category:books'] + responses: '200': description: OK content: application/json: schema: - title: pushEventsResponse - type: object - additionalProperties: false - required: - - message - properties: - message: - type: string - description: A message confirming the event push. + $ref: '../common/schemas/EventsResponse.yml' + examples: + Success: + summary: Events successfully sent to the Insights API. + description: >- + Success indicates that the Insights API received the events correctly, + and that event properties are formatted correctly. + Success doesn't imply that the event can be used by any Algolia feature. + For example, the Insights API doesn't check if the index name you provided exists, + or if the object IDs exist in your index. + value: {'status': 200, 'message': 'OK'} '400': - $ref: '../../common/responses/BadRequest.yml' + description: Bad Request. + content: + text/html: + schema: + type: string + title: HTML + examples: + BadRequest: + summary: Bad request. + description: This error doesn't return a JSON object, but HTML. + value: 'Error: Bad Request. Your client has issued a malformed or illegal request.' '401': - $ref: '../../common/responses/Unauthorized.yml' + description: Unauthorized + content: + application/json: + schema: + $ref: '../common/schemas/EventsResponse.yml' + examples: + Unauthorized: + summary: Invalid credentials. + description: You need to provide your application ID using the `X-Algolia-Application-ID` header and your (search) API key with the `X-Algolia-API-Key` header. + value: {'status': 401, 'message': 'Invalid credentials'} + '404': + description: Not Found. + content: + application/json: + schema: + $ref: '../common/schemas/EventsResponse.yml' + examples: + NotFound: + summary: Unsupported operation. + description: Check that you're using the correct URL. + value: {'status': 404, 'message': 'Path not supported by Insights REST API. Please have a look at [https://www.algolia.com/doc/rest-api/insights/](https://www.algolia.com/doc/rest-api/insights/) for the list of valid commands.'} + '405': + description: Method Not Allowed. + content: + application/json: + schema: + $ref: '../common/schemas/EventsResponse.yml' + examples: + MethodNotAllowed: + summary: Method not allowed. + description: Check, that you're using the `POST` method with the Insights API. Other methods aren't supported. + value: {'status': 405, 'message': 'Method Not Allowed'} '413': - $ref: '../../common/responses/UnprocessableEntity.yml' + description: Payload Too Large. + content: + application/json: + schema: + $ref: '../common/schemas/EventsResponse.yml' + examples: + PayloadTooLarge: + summary: Request body larger than 2 MB. + value: {'status': 413, 'message': 'Request Entity Too Large'} '422': - $ref: '../../common/responses/RequestEntityTooLarge.yml' + description: Unprocessable Entity. + content: + application/json: + schema: + $ref: '../common/schemas/EventsResponse.yml' + examples: + InvalidPayload: + summary: Incorrect event object. + value: {'status': 422, 'message': 'Invalid payload'} + NoEvents: + summary: No events. + description: >- + This can happen if you're sending an empty `events` array, + or if you try to send a single event object instead of the `events` array. + value: {'status': 422, 'message': 'No events to process'} + NoEventsField: + summary: Missing events attribute. + description: This can happen if you try to send an array of events directly instead of using the `events` attribute. + value: {'status': 422, 'message': 'Invalid type for field : expected insights.PublicEventsBatch, got array'} + EventNameRequired: + summary: Missing eventName attribute. + value: {'status': 422, 'message': 'EventName is required'} + WrongEventName: + summary: Event name too long or wrong characters. + value: {'status': 422, 'message': 'EventName must contain only visible ASCII characters, and be between 1 and 64 characters long'} + EventTypeRequired: + summary: Missing eventType attribute. + value: {'status': 422, 'message': 'EventType is required'} + WrongEventType: + summary: Wrong event type. + value: {'status': 422, 'message': 'EventType must be one of "click", "conversion" or "view"'} + IndexRequired: + summary: Missing index attribute. + value: {'status': 422, 'message': 'The index field is required'} + UserTokenRequired: + summary: Missing userToken attribute. + value: {'status': 422, 'message': 'The userToken field is required'} + WrongUserToken: + summary: Malformed user token. + value: {'status': 422, 'message': 'UserToken must contain only alphanumeric, equal, plus, slash, hyphen, or underscore characters, and be between 1 and 128 characters long'} + NoObjectIDsOrFilters: + summary: Missing objectIDs or filters attribute. + description: Each event must include either the `objectIDs` or `filters` attribute. + value: {'status': 422, 'message': 'Event should specify either some ObjectIDs or some Filters'} + BothDefined: + summary: Both objectIDs and filters attributes defined. + value: {'status': 422, 'message': 'Event should specify ObjectIDs or Filters, but not both'} + PositionsOnWrongEventType: + summary: Wrong combination of positions and eventType attributes. + value: {'status': 422, 'message': 'Only event of type click should specify the positions attribute'} + PositionsWithoutQueryID: + summary: Positions attribute without queryID. + description: Click events with the `positions` attribute require the `queryID` attribute. + value: {'status': 422, 'message': 'Event of type click with positions should specify a queryID'} + WrongPositionsValue: + summary: Wrong value in positions array. + description: Any value in the `positions` array must be greater than 0. + value: {'status': 422, 'message': 'Event of type click may only have strictly positive positions'} + WrongPositionsItems: + summary: Wrong number of items in positions array. + description: >- + For click events with the `queryID` and `objectIDs` attributes, + you must include the `positions` attribute with the same number of items as the `objectIDs` attribute. + value: {'status': 422, 'message': 'Event of type click should have the same number of ObjectIDs and Positions'} + WrongQueryID: + summary: Malformed query ID. + value: {'status': 422, 'message': 'Query ID must be a search query ID (32 characters hexadecimal string)'} + InvalidDataType: + summary: Wrong data type. + description: >- + This can happen if one or more of the attributes is a number instead of a string. + value: {'status': 422, 'message': 'Invalid type for field events: expected string, got number'} + InvalidTimestamp: + summary: Timestamp too old. + value: {'status': 422, 'message': 'The timestamp must be at most 4 days in the past'} + TooManyEvents: + summary: Too many events. + description: You can include up to 1,000 events in a single API request. + value: {'status': 422, 'message': 'Cannot process more than 1000 events in a batch'} diff --git a/specs/insights/spec.yml b/specs/insights/spec.yml index 72fa04d278..48b926801d 100644 --- a/specs/insights/spec.yml +++ b/specs/insights/spec.yml @@ -1,7 +1,11 @@ openapi: 3.0.2 info: title: Insights API - description: API powering the Insights feature of Algolia. + description: >- + The Algolia Insights API lets you collect events related to your search and discovery experience. + Events represent actions that users take on your app or website. + They unlock powerful features, such as recommendations, personalization, smarter search results, + and analytics that help you optimize your user experience. version: 1.0.0 components: securitySchemes: @@ -24,7 +28,9 @@ security: tags: - name: events x-displayName: Events - description: Events operations. + description: >- + Events represent user interactions with your website or app. + They include details like the event's name, type, a timestamp or a user token. x-tagGroups: - name: General tags: diff --git a/tests/CTS/methods/requests/insights/pushEvents.json b/tests/CTS/methods/requests/insights/pushEvents.json index b07116c7c2..b2128b07d3 100644 --- a/tests/CTS/methods/requests/insights/pushEvents.json +++ b/tests/CTS/methods/requests/insights/pushEvents.json @@ -17,29 +17,6 @@ 7, 6 ] - }, - { - "eventType": "view", - "eventName": "Product Detail Page Viewed", - "index": "products", - "userToken": "user-123456", - "timestamp": 1641290601962, - "objectIDs": [ - "9780545139700", - "9780439784542" - ] - }, - { - "eventType": "conversion", - "eventName": "Product Purchased", - "index": "products", - "userToken": "user-123456", - "timestamp": 1641290601962, - "objectIDs": [ - "9780545139700", - "9780439784542" - ], - "queryID": "43b15df305339e827f0ac0bdc5ebcaa7" } ] }, @@ -63,29 +40,6 @@ 7, 6 ] - }, - { - "eventType": "view", - "eventName": "Product Detail Page Viewed", - "index": "products", - "userToken": "user-123456", - "timestamp": 1641290601962, - "objectIDs": [ - "9780545139700", - "9780439784542" - ] - }, - { - "eventType": "conversion", - "eventName": "Product Purchased", - "index": "products", - "userToken": "user-123456", - "timestamp": 1641290601962, - "objectIDs": [ - "9780545139700", - "9780439784542" - ], - "queryID": "43b15df305339e827f0ac0bdc5ebcaa7" } ] }