changed 2 years ago
Published Linked with GitHub

💫 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 partner-support@segment.com 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. 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 partner-support@segment.com.


Kana Destination

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

Getting Started

Supported Methods

Kana supports the following methods, as specified in the Segment 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{:target="_blank"} within the Kana dashboard{: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 calls to create, update, merge and identify users in Kana.

analytics.identify('userId123', {
  name: "John Doe",
  email: 'john.doe@example.com',
  billingId: 'cus_Lp1bSKob4laHDD'
});

Kana looks for the following traits in Identify events which map to user fields in Kana:

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.

Track

Send 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. 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 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{:target="_blank"} within the Kana dashboard{: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.

See more on how to setup rules in the Kana dashboard.


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!

Select a repo