Segment

📘
Segment is a great way to ingest usage events with no code.

If you are already a Segment customer, Segment is the best way to start streaming usage events into Kable without writing any code. (And if you're not a Segment customer, consider checking it out -- Segment is pretty sweet!)

🚧
You can read more about using Segment to ingest Kable events in Segment's documentation.

Initial Setup

From the Segment web app, click Catalog then Destinations.
Search for Kable in the Destinations Catalog, and select Kable.
Click Configure Kable.
Choose which Source(s) should send data to Kable. You might configure Sources like a Node.js server running your API, a Snowflake instance warehousing your data, or an Amazon S3 bucket.
Configure your Segment Connection Settings:
1. Add your Kable Client ID and Kable API Key. (You can find your Kable Client ID and API Keys in the Company tab of your Kable dashboard.)
2. Specify which Segment event field corresponds to your customer's Client ID on Kable.
3. Map any other Segment event properties to Kable event fields.

Setting	Description	Examples
API Key	Your Kable API Key	`sk_test.h6kVNO3I...`
Kable Client ID	Your Kable Client ID	`kci_3c90e9ac92c6...`
Client ID Field	The field from your Segment events that corresponds to your customer's `clientId` on Kable.	`userId`, `context.groupId`, or `properties.customerId`
Properties Mappings	Map fields from Segment event `properties` to fields in Kable event `data`. More on mapping properties below.	`segmentX : kableX` `segmentY : kableY`

Kable Segment Settings

Mapping Properties

Kable automatically maps fields from Segment events onto Kable events. You can override default handling for certain fields. The following table describes the default mappings used to convert Segment properties to Kable data.

Kable Field	Mapped Segment Field
Client ID `clientId`	By default, Kable maps Segment's `userId` to Kable's `clientId`. You can override this default behavior by specifying a Client ID Field in your Segment Connection Settings. To map a nested Segment field, use dot notation. For example to use Segment's `groupId` within the `context` node, you might configure `context.groupId`, or to use a field called `customer` within `properties`, you might configure `properties.customer`.
Timestamp `timestamp`	Kable automatically maps Segment's `timestamp` to Kable's `timestamp`.
Transaction ID `transactionId`	Kable automatically maps Segment's `messageId` to Kable's `transactionId`.
Data `data`	Kable automatically maps Segment's `properties` to Kable's `data`. You can map Segment `properties` fields to different Kable `data` fields by specifying Properties Mappings in your Segment Connection settings. Let's say you had a Segment `properties` field `segmentFieldX`. If that field corresponded to some Kable Dimension with a key of `kableDimensionX`, you might include in your Segment Properties Mappings `segmentFieldX : kableDimensionX`. When ingesting a Segment event, then, that field would be transformed.

Kable Segment Properties Mappings

An Example

Let's look at an example Segment track event to see how it might be transmitted to Kable.

analytics.track({
  event: "your_event_type",
  userId: "yourcompanyuser_1234567890",
  properties: {
    segmentFieldX: "important data point",
    messageId: "msg_ABC123XYZ456", 
    objectCount: 12, 
    bankAccountBalance: 399.99,
  }
});

The Segment Track event above would be transformed and transmitted to Kable as:

curl --request POST \
     --url https://live.kable.io/api/v1/events/create \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'Kable-Client-ID: <YOUR_KABLE_CLIENT_ID>' \
     --header 'Kable-Client-Secret: <YOUR_KABLE_CLIENT_SECRET>' \
     --data '
{
  "clientId": "messageId",
  "timestamp": "2022-01-09T09:32:01Z", # Segment timestamp
  "transactionId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db", # Segment messageId
  "data": {
    "kableDimensionX": "important data point", # notice the property mapping here
    "messageId": "msg_ABC123XYZ456", 
    "objectCount": 12, 
    "bankAccountBalance": 399.99
  }
}