Segment

Ingesting usage events through 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

  1. From the Segment web app, click Catalog then Destinations.
  2. Search for Kable in the Destinations Catalog, and select Kable.
  3. Click Configure Kable.
  4. 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.
  5. 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.
SettingDescriptionExamples
API KeyYour Kable API Keysk_test.h6kVNO3I...
Kable Client IDYour Kable Client IDkci_3c90e9ac92c6...
Client ID FieldThe field from your Segment events that corresponds to your customer's clientId on Kable.userId, context.groupId, or properties.customerId
Properties MappingsMap fields from Segment event properties to fields in Kable event data.

More on mapping properties below.
segmentX : kableX
segmentY : kableY

Kable Segment SettingsKable 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 MappingsKable 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
  }
}