Script API

Overview

In some situations, you may have something you want to track where our point-and-click system is not ideal. For example, if your system has server generated user or session data, that is a good case to directly use our script API and have full control over what data you send to your tools.

We also have a few methods available that are useful for more advanced setups.

Identify

Identify lets you associate user data with behavior and record any number of traits.

Here is the full structure of an identify call:

bigPicture.identify([userId], [traits], [options], [callback]);

Method parameters:

Field Type Description
userId (optional) String A unique identifier for the user. We recommend using something unlikely to change like the database ID.
properties (optional) Object Collection of user traits that describe the user (email, name, plan. etc.)
options (optional) Object Different options for the call. For example, if you want to send a specific configuration to an integration or selectively send data to certain integrations.
callback (optional) Function A function that is called after a short timeout. This gives the browser time to make the requests before the next event, like a page change.

Examples

Let's say a visitor fills out a subscribe form on your website, and you want to create or update a contact in your integrations. The form includes data like the person's name, email address, and company name.

Here's what that would look like:

bigPicture.identify({
  name: "Elon Musk",
  company: "Tesla",
  email: "elon@tesla.com"
})

We will store this information locally, so if the customer leaves and comes back again several days later their data will be available. Then we will either create or update the contact information in each integration you have active.

Let's say the customer then comes back and signs up for your website. You now have a database ID for that contact and can add that as the user ID for your customer.

bigPicture.identify("123", {
  name: "Elon Musk",
  company: "Tesla",
  email: "elon@tesla.com"
})

Certain integrations require a user ID in order to send data. So if a user ID is not provided we will default to using a dynamically generated anonymous ID.

Track

The track method is a way to track any action your customer has done.

Each call includes a name like New Signup and optional properties describing the action.

Here is the full structure of a track call:

bigPicture.track([event], [properties], [options], [callback]);

Method parameters:

Field Type Description
event (required) String Name of the action that a user has done.
properties (optional) Object Collection of properties that describe the event (type, cost, plan. etc.)
options (optional) Object Different options for the call. For example, if you want to send a specific configuration to an integration or selectively send data to certain integrations.
callback (optional) Function A function that is called after a short timeout. This gives the browser time to make the requests before the next event, like a page change.

Examples

bigPicture.track("New Signup", {
  plan: "Pro",
  revenue: 99.99
})

Page

The page method lets you track page views throughout your website.

This is usually easier to setup in the point-and-click system, as you can use URL Targeting to fire page view events on certain pages, or whenever the URL changes. For example, if you have a single page app where the page doesn't reload - also known as a virtual page view.

Here is the full structure of a page call:

bigPicture.page([category], [name], [options], [callback]);

Method parameters:

Field Type Description
category (required) String The category of the page. Useful if you have a lot of pages that are grouped together, such as ecommerce.
name (optional) String The name of the page.
options (optional) Object Different options for the call. For example, if you want to send a specific configuration to an integration or selectively send data to certain integrations.
callback (optional) Function A function that is called after a short timeout. This gives the browser time to make the requests before the next event, like a page change.

Examples

The simplest form.

bigPicture.page()

If you want to pass a name:

bigPicture.page('Contact Us')

Group

The group method lets you associate a user with a group, organization, business, team, etc. Whatever you want to call it.

Here is the full structure of a group call:

bigPicture.group([groupId], [traits], [options], [callback]);

Method parameters:

Field Type Description
groupId (required) String The group ID to associate with the current user.
traits (optional) Object A collection of traits to describe the group.
options (optional) Object Different options for the call. For example, if you want to send a specific configuration to an integration or selectively send data to certain integrations.
callback (optional) Function A function that is called after a short timeout. This gives the browser time to make the requests before the next event, like a page change.

Examples

bigPicture.group('Tesla, Inc.', {
  isCustomer: true,
  industry: 'Energy'
})

The group call works similar to the identify call and will store the data in the browser's local storage.

Ready

The ready method is useful if you want to write some custom code that references any of the integrations directly. You can pass a callback, which will be called once all the integrations are loaded.

Here's an example of setting some custom Amplitude data:

bigPicture.ready(function() {

  var revenue = new amplitude.Revenue().setProductId('productIdentifier').setPrice(10.99).setRevenueType('purchase');
  amplitude.logRevenueV2(revenue);

})

Here is the structure of a ready call:

bigPicture.ready([[callback]);

Method parameters:

Field Type Description
callback (optional) Function A function that is called after a short timeout. This gives the browser time to make the requests before the next event, like a page change.

An important note for the ready method:

The ready method is only called once ALL integrations are loaded. If the visitor is using an ad blocker that blocks the loading for some integrations (Facebook, AdWords, etc.), then there is a chance your code will never run. So we recommend not placing any logic here that is critical to your site functionality.

Selecting Destinations

An integrations object can be passed in the options of all method calls that enables you to control which integrations you want the data sent to. By default, all integrations are active.

Example

Send data only to Google Analytics and Amplitude.


bigPicture.track('Test event', {
  active: true,
  isCustomer: true,
}, {
  integrations: {
    'All': false,
    'Google Analytics': true,
    'Amplitude': true
  }
});