# 💫 Segment Partner Destination Documentation Template

> Hi Partners 👋🏼
>
> Welcome to Segment - glad to have you onboard! This doc serves as a guideline for your team to create best-in-class documentation alongside your amazing product.
>
> At Segment, we believe that documentation is crucial in delivering the best experience for our mutual customers so we want to think with the following mindset:
>
>+ Be succinct and simple in your writing. Reduce text bloat where possible.
>+ Avoid 1st person language as it’s confusing for customers if they don’t know who wrote the docs (Segment or the Partner).
>+ Use the active voice - instead of "The destination will do this." write something like "The destination does this."
>+ Where pre-reading is required, hyperlink to other more generic parts of Segment’s (or your) documentation.
>
>+ Provide actionable code samples for each API method.
>
>+ If you would like to include screenshots, send the original image to us via [e-mail] with naming corresponding to where you've included it within the Markdown below. We prefer PNG images within 400px - 1200px. If you'd like to submit a GIF, keep under 15MB. Generally you should be able to write these out as text, so only use them when there's something really hard to explain.
>
> The below template intends to provide a standardized structure. Please **make a copy** of this template for editing and submit to the Segment team as a new note on [HackMD.io](https://hackmd.io/). You can view a sample doc as reference here: https://segment.com/docs/connections/destinations/catalog/clearbrain/.
>
> If a section does not apply to your integration, feel free to remove. Please don’t create separate sections unless absolutely necessary. In most cases, creating a H3 (###) sub-heading under an existing section is the best option!
>
> If you have any questions in the meantime, please reach out to our team at [e-mail].

---
Kana Destination
---

[Kana](https://www.usekana.com/?utm_source=segment&utm_medium=docs) 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.

This destination is maintained by Kana. For any issues with the destination, [contact the Kana team](mailto:[e-mail]).

## Getting Started

### Supported Methods
Kana supports the following methods, as specified in the [Segment Spec](/docs/connections/spec).

{% include content/connection-modes.md %}

### Setup
1. From the Destinations catalog page in the Segment App, click **Add Destination**.
2. Search for "Kana" in the Destinations Catalog, and select the "Kana" destination.
3. Choose which Source should send data to the "Kana" destination.
4. Go to the [API Key page](https://dashboard.usekana.com/developer){:target="_blank"} within the [Kana dashboard](https://dashboard.usekana.com){:target="_blank"}.
5. Copy the API Key from 'Admin API (Backend) Key'.
6. Enter the API Key in the Kana destination settings in Segment.

## Identify

Send [Identify](/docs/connections/spec/identify) calls to create, update, merge and identify users in Kana.

analytics.identify('userId123', {
  name: "John Doe",
  email: '[e-mail]',
  billingId: 'cus_Lp1bSKob4laHDD'
});

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):

| Field | Required? | Description |
| -------- | -------- | -------- |
| `userId` | *Required* | Maps to the `id` of a user in Kana. This is the external identifer of your user.
| `traits.name` | *Optional* | Maps to the `name` of a user in Kana.
| `traits.email` | *Optional* | Maps to the `email` of a user in Kana. |
| `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. |

*Warning Hint Block:* All other traits will be dropped as they do not map to a field in Kana.

### Creating, updating or merging

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`.

The following examples illustrate when a user will be created, updated or merged in Kana based on (1) what is sent in the Segment event payload, and (2) what users & which details are present in Kana:


*Info Hint Block:* 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` which matches. However, in the event they 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.

[See more on how creating, updating and merging works](https://kana-1.gitbook.io/kana-docs).

## Track

Send [Track](/docs/connections/spec/track) calls to Kana in order to record when a customer has used a particular feature. For example:

analytics.track('Message Sent', {
  featureId: 'messages',
  delta: 1
});

Kana looks at all properties in Track events for [mapping rules](#kana-rules). However, Kana considers the following properties to be special:

| Field | Required? | Description |
| -------- | -------- | -------- |
| `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.
| `properties.delta` | *Optional* | Used to record how much of a feature someone has used. Defaults to `1`. |

*Warning Hint Block:* Events sent in without a `userId` (aka. anonymous events) will be dropped and responded to with a `400 Bad Request` error.

### Mapping Rules
There are two ways to map Segment events to Kana features:

* Providing a `properties.featureId` field within a Segment event
* **Setting rules to map events to features within the Kana dashboard**

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.

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.

*Info Hint Block:* 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](https://segment.com/docs/guides/filtering-data/).

[See more on how to setup rules in the Kana dashboard](https://kana-1.gitbook.io/kana-docs).

---

> Congratulations! 🎉 You’ve finished the documentation for your Segment integration. If there’s any additional information or nuance which did not fit in the above template and that you want to share with our mutual customers, feel free to include these as a separate section for us to review. If not, you may now submit this doc to our team via your designated Slack Channel and we’ll respond with updates when we publish it and your integration!