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.

Intel Ready

This is one of our newer methods associated with our Intel product. This method enables you to pass a callback, which will be called with all the available Intel data once ready.

You could use this to power realtime website personalization, qualify the lead for targeted ad retargeting, or send the data to an endpoint like Zapier for further handling.

Here is the structure of the intel ready method:

bigPicture.intelReady([callback])

Method parameters:

Field Type Description
callback (optional) Function A function that is called once the Intel data is available, with the first parameter of the callback containing the data.

Here is the structure of the Intel data:


{
    "person": {
        "employment": {
            "title": "Founder",
            "role": "founder",
            "seniority": "executive"
        },
        "geo": {
            "city": "Berkeley",
            "state": "California",
            "stateCode": "CA",
            "country": "United States",
            "countryCode": "US",
            "lat": 37.9073,
            "lng": -122.282
        },
    },
    "device": {
        "geoLocation": {
            "city": "Berkeley",
            "majorCity": "San Jose",
            "state": "California",
            "postal": "94710",
            "stateCode": "CA",
            "country": "United States",
            "countryCode": "US",
            "continent": "North America",
            "lat": 37.8726,
            "lng": -122.3044
        },
        // misc device info
    },
    "company": {
        "name": "BigPicture.io",
        "legalName": "Big Picture Technologies, Inc.",
        "domain": "bigpicture.io",
        "tags": [
            "Media",
            "Software",
            "Technology"
            ...
        ],
        "tech": [
            "activecampaign",
            "bigpicture.io",
            "drift",
            "facebook_custom_audiences",
            "google_analytics"
            ...
        ],
        "category": {
            "sector": "Technology",
            "industryGroup": "Technology",
            "industry": "Software & Computer Services",
            "subIndustry": "Internet"
        },
        ...
    }
}

For more info on what data is available, check out our enrichment docs.

Examples

Below are few examples on how to use the method. We are working on ways to make this data easier to work with - without having to get into the code.

If you need help or have any questions, feel free to email us at support@bigpicture.io.

Example 1

Personalize website based on the vistor's company industry:


bigPicture.intelReady(function(data) {

  // Easier reference to the company data
  var company = data.company;

  // First check if company data is available
  if (!company) {
    return;
  }

  // If visitor company is in the health care industry
  if (company.category.subIndustry === 'Health Care Providers') {

    // Change header to an industry specific message
    $('h1').text('We specialize in providing health care solutions!');
  }
})

Example 2

If the company matches your criteria for industry and size, send an event named 'Qualified Lead' to Facebook, which you can then use to build a targeted custom audience.


bigPicture.intelReady(function(data) {

  // Easier reference to the company data
  var company = data.company;

  // First check if company data is available
  if (!data.company) {
    return;
  }

  // If visitor company is a 'Broadline Retailers' (like Walmart) and has more than 10,000 employees
  if (company.category.subIndustry === 'Broadline Retailers' && company.metrics.employees >= 10000) {

    // Send event to only Facebook
    bigPicture.track('Qualified Lead', {
      name: company.name,
      subIndustry: company.category.subIndustry,
      employees: company.metrics.employees
    }, {
      integrations: {
        'All': false,
        'Facebook Pixel': true,
      }
    });

  }
})

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
  }
});