Typescript

​

Installation

To use the Dawn SDK, start by installing with npm, yarn, pnpm, or bun

npm install @dawn-analytics/js

Before using the SDK, you need to set the write_key variable with your SDK write key. You can obtain a write key by logging in to your dashboard, or contacting the Dawn team.

import { Analytics } from "@dawn-analytics/js";

const dawn = new Analytics({ writeKey: DAWN_API_KEY });

​

Tracking AI Interactions

To track AI interactions, you can use the trackAi function. It takes the following parameters:

• userId (string): The unique identifier of the user.

• event (string): The name of the AI event you want to track.

• input (optional string): The input provided by the user. (Either this or output is required)

• output (optional string): The output generated by the AI. (Either this or input is required)

• attachments (optional array): An array of attachment objects (see #attachments for details).

• model (optional string): The name of the AI model used.

• convoId (optional string): The conversation ID associated with the interaction.

• properties (optional object): Additional properties associated with the AI event.

Example usage:

dawn.trackAi({
  userId: "user123",
  event: "user_message",
  input: "What is the weather like today?",
  output: "The weather is sunny and warm.",
  model: "gpt-4",
  convoId: "conv789",
  properties: {
    os_build: "17.1",
  },
  attachments: [
    {
      type: "text",
      name: "Additional Info",
      value: "A very long document",
      role: "input",
    },
    { type: "image", value: "https://example.com/image.png", role: "output" },
    {
      type: "iframe",
      name: "Generated UI",
      value: "https://newui.generated.com",
      role: "output",
    },
  ],
});

​

Attachments

Attachments allow you to include context from the user (e.g. an attached image), or stuff that the model outputted (whether that is an image, document, code, or even an entire web page).

Each attachment is an object with the following properties:

• type (string): The type of attachment. Can be “code”, “text”, “image”, or “iframe”.

• name (optional string): A name for the attachment.

• value (string): The content or URL of the attachment.

• role (string): Either “input” or “output”, indicating whether the attachment is part of the user input or AI output.

• language (optional string): For code attachments, specifies the programming language.

Example of different attachment types:

const attachments = [
  {
    type: "code",
    name: "Example Code",
    value: "console.log('Hello, World!');",
    role: "input",
    language: "javascript",
  },
  {
    type: "text",
    name: "Additional Info",
    value: "Some extra text",
    role: "input",
  },
  { type: "image", value: "https://example.com/image.png", role: "output" },
  { type: "iframe", value: "https://example.com/embed", role: "output" },
];

dawn.track_ai({
  userId: "user123",
  event: "code_review",
  input: "Please review this code",
  attachments: attachments,
  // ... other properties
});

​

PII Redaction

Read more on how Dawn handles privacy and PII redaction here. You can enable client-side PII redaction when intializing the Analytics class like so:

const dawn = new Analytics({ writeKey: DAWN_API_KEY, redactPii: true });

​

Identifying Users

To associate traits with users, you can use the identify function. It takes the following parameters:

• user_id (str): The unique identifier of the user.

• traits (Dict[str, Union[str, int, bool, float]]): The traits associated with the user.

Example usage:

dawn.setUserDetails({
  userId: "user123" //Your unique id here,
  traits: {
    os: "macOS",
    name: "John Doe",
    email: "john@doe.com"
    plan: "paid" //we recommend 'free', 'paid', 'trial'
  },
});

​

Tracking Other Events

To track normal analytics events, you can use the track function. It takes the following parameters:

• user_id (str): The unique identifier of the user.

• event (str): The name of the event you want to track.

• properties (Optional[Dict[str, Union[str, int, bool, float]]]): Additional properties associated with the event like location, OS version, etc.

Example usage:

dawn.track({
  userId: "user123",
  event: "product_viewed",
  properties: {
    product_id: "item456",
    price: 9.99,
  },
});

​

Close when finished

dawn.close();

​

Error Handling

If an error occurs while sending events to Dawn, an exception will be raised. Make sure to handle exceptions appropriately in your application.

​

Debugging

If you want to enable debug logs to see the events being added to the buffer, you can set the debugLogs variable to true:

new Analytics({
  writeKey: DAWN_API_KEY,
  debugLogs: true,
});

That’s it! You should be ready to go. Please let us know if you have any questions.