@usesummit/browser

Summit JS SDK - Browser

Summit powers engaging apps for sales, marketing, and product teams to deploy and use anywhere.

You can use this SDK to call your Summit apps over API from your website or apps. The SDK isn't mandatory but ensures a correct configuration for Summit's analytics and CRM integration features.

🌱 The Summit SDK is fresh out of the oven and in an alpha state. Things might change at any time, but we're happy to collaborate on your implementation and make sure we don't break things going forward. You can reach me at [e-mail] if you're planning on rolling out your own implementation and have questions or concerns.

Usage

Initializing

Initialize a Summit client instance by running:

import Summit from '@usesummit/browser';

const summit = new Summit('your-optional-api-key');

// Store identifiers in cookies
const summit = new Summit({ apiKey: 'your-api-key', cookie: true });

// Configure cookies, for example, to store them on your top-level domain
const summit = new Summit({
    apiKey: 'your-api-key',
    cookie: {
        domain: 'acme.inc',
    },
});

You can also use the SDK to embed hosted apps, and identify your visitors.

By default, session & visitor tracking identifiers are stored in sessionStorage and localStorage respectively, but you can opt-in to cookies if you prefer that.

Running

Run your app by calling summit.run() with these options:

• app: { app: 'org-slug/id/app-slug', apiKey: 'app-api-key' }. You can get this information from the API tab in the project settings dialog. The apiKey is optional if you've initialized the client with an API key.
• parameters: a dictionary with your app's parameters. If your leave out any parameters, it will run using the default values in the Summit model driving the app logic.
• options: { start?: 'iso-string', end?: 'iso-string', resolution?: 'month' | 'year' | … }

run() returns a Promise that resolves into an object with this structure:

{
  groups: {
    from: number;
    to: number;
    title: string;
    is_partial: boolean;
  }[],
  results: {
    group: string; // Refers to `groups[].title`
    values: Record<string, number>
  }[]
}

You can read more on the API input & output in our API documentation.

Embedding

Embedding a hosted app is the easiest way to get started with Summit. Add a target div to your HTML, then instruct Summit to embed the div there:

<div id="my-summit-app"></div>

summit.embed(
    { app: 'org-slug/id/app-slug', embedKey: 'app-embed-key' },
    '#my-summit-app'
);

Et voila!. You might want to wrap my-summit-app in some styles to enforce an aspect ratio, we found that 9:16 on mobile screens (portrait) and 4:3 on tablets & bigger works well.

Using the embed() method will enrich your embed with the session tracking identifiers, so that multiple embeds and summit.run() calls can all be linked back to the same visitor.

Identifying

If you have a newsletter subscription form, an Intercom integration, … that allows you to capture the current user's e-mail address, you can link that to their app usage by calling summit.identify('email-address').

That e-mail address will then be linked to all past and future runs for that user.