Skip to content

Commit e746aca

Browse files
bot-docsteambot-docsteam
authored
Merge pull request #640 from segmentio/repo-sync
repo sync
2 parents b18b2c2 + 3f53000 commit e746aca

File tree

1 file changed

+95
-0
lines changed
  • src/connections/destinations/catalog/kana

1 file changed

+95
-0
lines changed

‎src/connections/destinations/catalog/kana/index.md

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
title: Kana Destination
3+
id: 62d130412ffed8c0b170560f
4+
beta: true
5+
---
6+
7+
[Kana](https://www.usekana.com/?utm_source=segment&utm_medium=docs){:target="_blank"} provides pricing infrastructure for internet businesses. This destination allows for a low-code integration of Kana, using Segment events to record the usage of your features in order to measure entitlement, gain insights and ensure customers are charged correctly.
8+
9+
This destination is maintained by Kana. For any issues with the destination, [contact the Kana team](mailto:[email protected]).
10+
11+
## Getting Started
12+
13+
{% include content/connection-modes.md %}
14+
15+
1. From the Destinations catalog page in the Segment App, click **Add Destination**.
16+
2. Search for "Kana" in the Destinations Catalog, and select the "Kana" destination.
17+
3. Choose which Source should send data to the "Kana" destination.
18+
4. Go to the [API Key page](https://dashboard.usekana.com/developer){:target="_blank"} within the [Kana dashboard](https://dashboard.usekana.com){:target="_blank"}.
19+
5. Copy the API Key from 'Admin API (Backend) Key'.
20+
6. Enter the API Key in the Kana destination settings in Segment.
21+
22+
23+
## Supported methods
24+
25+
Kana supports the following methods, as specified in the [Segment Spec](/docs/connections/spec).
26+
27+
### Identify
28+
29+
Send [Identify](/docs/connections/spec/identify) calls to create, update, merge and identify users in Kana.
30+
31+
```js
32+
analytics.identify('userId123', {
33+
name: "John Doe",
34+
email: '[email protected]',
35+
billingId: 'cus_Lp1bSKob4laHDD'
36+
});
37+
```
38+
39+
Kana looks for the following traits in Identify events which map to [user fields in Kana](https://kana-1.gitbook.io/kana-docs/reference/admin-api-backend-reference/objects#user){:target="_blank"}:
40+
41+
| Field | Required? | Description |
42+
| ---------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
43+
| `userId` | *Required* | Maps to the `id` of a user in Kana. This is the external identifier of your user. |
44+
| `traits.name` | *Optional* | Maps to the `name` of a user in Kana. |
45+
| `traits.email` | *Optional* | Maps to the `email` of a user in Kana. |
46+
| `traits.billingUserId` | *Optional* | Maps to the `billingId` of a user in Kana. Must be the customer `id` for either Stripe or Chargebee as valid billing providers. |
47+
48+
> warning ""
49+
> All other traits will be dropped as they do not map to a field in Kana.
50+
51+
#### Creating, updating or merging
52+
53+
Kana looks at the `userId` and `email` to determine when to create, update or merge a user. The `userId` takes precedence as the canonical identifier. Kana allows for multiple users to have the same `email`.
54+
55+
> info ""
56+
> Users which were initially imported from Stripe may have no `userId` but could have an `email`. Kana will try update or merge these users when Segment events come in with an `email` that matches. However, in the event these users could not be merged (likely meaning there are multiple users with the same email and one was a Stripe import which has no `userId`), Kana will flag these users to you in the Kana dashboard. There will be two boxes - one calling out users without a `billingId` and one calling out users which have the same `email`. You will be able to merge or delete these users in case it's necessary.
57+
58+
[See more on how creating, updating and merging works](https://kana-1.gitbook.io/kana-docs){:target="_blank"}.
59+
60+
### Track
61+
62+
Send [Track](/docs/connections/spec/track) calls to Kana in order to record when a customer has used a particular feature. For example:
63+
64+
```js
65+
analytics.track('Message Sent', {
66+
featureId: 'messages',
67+
delta: 1
68+
});
69+
```
70+
71+
Kana looks at all properties in Track events for [mapping rules](#mapping-rules). However, Kana considers the following properties to be special:
72+
73+
| Field | Required? | Description |
74+
| ---------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
75+
| `properties.featureId` | *Optional* | Used to map events to features directly. Should correspond to the `id` of a feature in Kana. Defaults to the any [mapping rules](#kana-rules) if not present. |
76+
| `properties.delta` | *Optional* | Used to record how much of a feature someone has used. Defaults to `1`. |
77+
78+
> warning ""
79+
> Events sent in without a `userId` (aka. anonymous events) will be dropped and responded to with a `400 Bad Request` error.
80+
81+
### Mapping Rules
82+
There are two ways to map Segment events to Kana features:
83+
84+
* Providing a `properties.featureId` field within a Segment event
85+
* **Setting rules to map events to features within the Kana dashboard**
86+
87+
The latter can be used as a no-code solution (which also won't muddy data to other destinations), whereby Kana will look at incoming events and process them alongside rules you have defined to attribute them to features.
88+
89+
These rules can be created on the [Segment Integration page](https://dashboard.usekana.com/integrations/segment/rules){:target="_blank"} within the [Kana dashboard](https://dashboard.usekana.com){:target="blank"}. They can be set based on the name and properties of a track event with multiple AND conditions if required.
90+
91+
> info ""
92+
> All events will be sent from your source to Kana and stored there - no matter whether these will be used to record feature usage or not. Events which could not map to features are exposed within Kana. Any rules created afterwards will retroactively apply to these events, meaning events will reprocess against these new rules in an attempt to map them to features. If there are events you do not want to send to Kana (as they will never be used to record feature usage) then it's recommended that you [filter these events from sending](/docs/guides/filtering-data/).
93+
94+
95+
[See more on how to setup rules in the Kana dashboard](https://kana-1.gitbook.io/kana-docs).

0 commit comments

Comments
 (0)