Home > API Documentation > Segmenting API

Segmenting API

*SharpSpring Marketing Automation Users: This article is not applicable if you are a SharpSpring Marketing Automation user*

The Segmenting API lets you add users to Retargeting Audiences in SharpSpring Ads based on javascript events that fire in the browser. In this way, you can go beyond retargeting users based on page views and instead retarget users based on actions they take or based on first-party CRM data that you have about the user.

Once the SharpSpring Ads site tracking tag is on your site or app, it will enable you to fire both retargeting lists and conversion goals based on "events" you define in your SharpSpring Ads account.

Below we offer an intro to our API and some basic examples. For specific use cases and example code, see our Tracking API Cookbook. If you have questions or suggestions, please write us at ads@sharpspring.com.


Tracking Basics

You will interact with the SharpSpring Ads API via the _pq variable. _pq behaves very similarly to the Google Analytics _gaq variable. _pq is a "first in, first out" event queue, and allows you to add events to be fired without worrying about whether the SharpSpring Ads tag has been parsed by the web browser yet. You will need to ensure that you have defined _pq as an empty array the first time you use it, and you will then push events onto the queue.

Quick Example

You may wish to fire a conversion after a user clicks a sign-up button on your site.

To do this:

  1. Create a conversion goal of type "Javascript Event" within the Perfect Audience app.
  2. Title it "Sign Up Button Click" and in the Javascript Event field type "SignUp".
  3. Next, in your app code you will need to code it to fire the "SignUp" event when someone clicks the button. Here's how it should look:
  4. window._pq = window._pq || [];
    _pq.push(['track', 'SignUp']);
  5. Now, anytime someone clicks on that button, the "SignUp" event will be fired. Our tag will pick it up and count it as a conversion.

NOTE: The text you pass into the tracking function needs to match the "event" text on your conversion goal EXACTLY.

Using the Segmenting API to pass order IDs and revenue values into conversion goals for attribution

If you wish to attribute conversions to a specific identifier within your application, such as a purchase order ID, it's as easy as passing that identifier as as option in the last parameter of the "track" event.

If you want to include revenue data for a conversion, you can pass that data in using the same method:

window._pq = window._pq || [];
_pq.push(['track', 'SignUp', {orderId: '12345', revenue: 20}]);

This last parameter is optional, but if included, will allow you to gain more insight into your conversions.

Tracking product views

This functionality is part of SharpSpring Ads' Dynamic Ads.

SharpSpring Ads "Product Tracking" allows you to associate your Product IDs with your visitors similar to the way you work with "event" Retargeting Lists today. You will then be able to serve highly-targeted Dynamic Product ads to your visitors, showing them the exact products they were interested in purchasing from you.

In the script below, you will just need to replace the myProductId with the actual product ID you use - this might be an internal ID, a Manufacturer Part Number (mpn), etc. You will want this on every page where you have products available, like the individual product pages and your shopping cart. To track multiple product IDs in a single page view, run _pq.push(['trackProduct', 'myProductId']) once for each product ID.

window._pq = window._pq || [];
_pq.push(['trackProduct', 'myProductId']); 


There are a few methods to help test that SharpSpring Ads javascript events are firing correctly. You may run these from a javascript console (Chrome Developer Tools or Firebug in Firefox).

_pq.push(['track', 'eventName']) will return a boolean to tell you whether or not the event was fired.

_pa.segmentEvents and _pa.conversionEvents will return lists of your event-type segments and event-type conversions, so you can test in your browser that your event pixels are set up properly.

A Note on Caching

Our javascript tag is served from a CDN to ensure the best possible performance on your website. We use 30-minute cache headers. This means that any new segments and conversions you create will take up to 30 minutes to appear in your script tag. So if you don't see a segment firing right away, don't worry! Contact us if you have any questions about pixel performance.