Skip to content

Algolia insights update docs #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 4 commits into
base: develop
Choose a base branch
from
Draft

Algolia insights update docs #1

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a59da8b
chore: remove references to event renaming
Mar 6, 2023
18e5087
chore: add details about clickAnalytics
Apr 4, 2023
669e2e3
docs: add images for api keys
Apr 5, 2023
8a8199e
Merge branch 'segmentio:develop' into algolia-insights-update-docs
wwalser Apr 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added src/connections/destinations/catalog/algolia-insights/images/mapping_tab.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/connections/destinations/catalog/algolia-insights/images/mapping_tab_edit.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
74 changes: 19 additions & 55 deletions src/connections/destinations/catalog/algolia-insights/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ beta: true
redirect_from: '/connections/destinations/catalog/algolia/'
id: 5d373a350abf930001a6b70f
---
[Algolia Insights](https://www.algolia.com/products/analytics/) lets you push events related to how your product is being used. Sending those events is a required step for using several Algolia features:
This [Algolia Insights](https://www.algolia.com/products/analytics/) destination is a means of facilitating sending [Insights Events](https://www.algolia.com/doc/guides/sending-events/getting-started/). Sending these events is a required step for using several Algolia features:

- Click and conversion analytics
- A/B Testing
Expand All @@ -24,31 +24,37 @@ This destination is maintained by [Algolia](https://www.algolia.com/). For any i
2. Search for "Algolia" in the Catalog, select it, and choose which of your sources to connect the destination to.
3. Enter the "App ID" & "API Key" into your Segment Settings UI which you can find on the Algolia Dashboard, under API Keys menu.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Enter the "App ID" & "API Key" into your Segment Settings UI which you can find on the Algolia Dashboard, under API Keys menu.

Can we show a screenshot of where these items are in the Algolia Dashboard?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep will add those in today! Makes a lot of sense to show where they're located


_**NOTE:** The Algolia Insights Destination is not a plug-and-play integration. It requires you to modify your frontend code to send additional Algolia-related data like index name, queryID, etc._
> _**NOTE:** The Algolia Insights Destination is not a plug-and-play integration. It requires you to modify your frontend code to send additional Algolia-related data like index name, queryID, etc._

To access your queryID, make sure clickAnalytics are enabled in your search event. If you're using Insights.js this will look like
```js
index.search('query', {
userToken: 'user-1',
clickAnalytics: true
})
```

Once this is enabled you will be able to send properties like queryId in your segment events. You can read more about how to send Algolia-related data to Segment from [the documentation at Algolia](https://www.algolia.com/doc/guides/sending-events/implementing/connectors/segment/).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good call linking to our docs.


## Mapping Events

By default, Algolia has set up mappings for Product Clicked, Product Viewed and Order Completed events. If your event structure doesn't match the spec you can update this by using the Mapping Tab.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read from top to bottom, the reader doesn't know what 'the spec' is at this point in the document. We should either more the explination of that up to this point from below.

For a full list of required properties for each event type, see the Spec: V2 Ecommerce Events

Or this should be reworded to not include a reference to 'the spec'.

It'd also be reasonable to simply repeat ourselves here and lower in the document where we use the fully worded "Spec: V2 Ecommerce Events" and link to the ecommerce 2.0 events spec.


You can read more about how to send Algolia-related data to Segment from [the documentation at Algolia](https://www.algolia.com/doc/guides/sending-events/implementing/connectors/segment/).
![Mappings Tab](images/mapping_tab.png)

![Edit Mappings](images/mapping_tab_edit.png)

## Track

If you're not familiar with the Segment Specs, take a look to understand what the [Track method](/docs/connections/spec/track/) does.

Algolia supports the following six events from Segment's [Ecommerce Spec](/docs/connections/spec/ecommerce/v2/).
Algolia supports the following events from Segment's [Ecommerce Spec](/docs/connections/spec/ecommerce/v2/).

<table>
<tr>
<td>Supported Events</td>
<td>Description</td>
</tr>
<tr>
<td><code>Product List Viewed</code></td>
<td>Fire this event when a visitor views a product list or category.</td>
</tr>
<tr>
<td><code>Product List Filtered</code></td>
<td>Fire this event when a visitor filters a product list or category.</td>
</tr>
<tr>
<td><code>Product Viewed</code></td>
<td>Fire this event when a visitor views a product.</td>
Expand All @@ -57,10 +63,6 @@ Algolia supports the following six events from Segment's [Ecommerce Spec](/docs/
<td><code>Product Clicked</code></td>
<td>Fire this event when a visitor clicks a product.</td>
</tr>
<tr>
<td><code>Product Added</code></td>
<td>Fire this event when a visitor adds a product to their shopping cart.</td>
</tr>
<tr>
<td><code>Order Completed</code></td>
<td>Fire this event whenever an order/transaction was successfully completed by the customer.</td>
Expand All @@ -70,31 +72,13 @@ Algolia supports the following six events from Segment's [Ecommerce Spec](/docs/
For a full list of required properties for each event type, see the [Spec: V2 Ecommerce Events](/docs/connections/spec/ecommerce/v2/)

```js
analytics.track('Product List Viewed', {
index: "my-index-name",
queryID: "Algolia queryID", // required only for Click Analytics,
products: [{
objectID: "hit objectID",
// ... other required properties from the spec
}]
})

analytics.track('Product List Filtered', {
index: "my-index-name",
filters: [
{ type : "free_delivery", value: "true" }
],
// ... other required properties from the spec
})

analytics.track('Product Viewed', {
objectID: "hit objectID",
index: "my-index-name",
queryID: "Algolia queryID", // required only for Click Analytics,
// ... other required properties from the spec
})


analytics.track('Product Clicked', {
objectID: "hit objectID",
position: hitPositionOnIndex, // number
Expand All @@ -103,13 +87,6 @@ analytics.track('Product Clicked', {
// ... other required properties from the spec
})

analytics.track('Product Added', {
objectID: "hit objectID",
index: "my-index-name",
queryID: "Algolia queryID", // required only for Click Analytics,
// ... other required properties from the spec
})

analytics.track('Order Completed', {
index: "my-index-name",
queryID: "Algolia queryID", // required only for Click Analytics,
Expand All @@ -126,17 +103,4 @@ analytics.track('Order Completed', {
Track calls will be sent to Algolia as a `track` event, and appear in your Click Analytics, A/B Testing and Personalization dashboard.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a strange line. Can you make heads or tails of it? Insights events are not sent to Algolia "as a track event". They are sent to us as… "events". They have an eventType field, but those are one of 'view', 'click' or 'conversion'. I think this needs to be reworded or removed.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah this was in the original documentation, I thought it was just me not fully understanding it. I'll just remove this entirely



_**NOTE:** If you send anonymous activity to Algolia, it will not be connected to activity attributed to that same user once they are identified._


## Renaming Events

If you are already sending events of which the names are out of the spec, you need to rename them for Algolia to understand correctly. It doesn't necessarily mean you need to modify your code.

Go to the destination settings and click "Rename Events".

![Destination Settings](images/destination_settings.png)

You can put your current event names on the left and the event names following the spec on the right.

![Rename Events](images/rename_events.png)
> _**NOTE:** If you send anonymous activity to Algolia, it will not be connected to activity attributed to that same user once they are identified._