Skip to content

Audience Segments: How To Integrate offers a few different ways to segment your audience in the dashboard, isolating a subset of users while also maintaining a view of your entire readership. Check out our blog post: 3 Ways to Use Audience Segmentation to Fine-Tune Your Content Strategy.

From a technical perspective there are two primary types of segments:

  1. Segments based on standard data – Standard data supports segmenting by geography (based on Geo IP lookups), campaigns (based on UTM or ITM parameters), or referring URL.
  2. Segments based on custom data – Commonly used to segment by subscription or registration status, but can be based on any method you choose to better understand your audience.

Depending on your plan, segment tracking may result in additional charges. Contact your account manager or for more information.

Audience segments integration overview

Segments based on standard data

For geographic, campaign, or referrer segments, no integration changes are necessary. Simply contact your account manager or with the details of the segments you’d like to add. For Geographic Segments, we can leverage your visitors’ IP using MaxMind GeoIP codes and Nielsen US DMA codes to separate your audience by the following options:

  • Continent
  • Global Regions (APAC, EMEA, LATAM, etc.)
  • Country
  • Subdivisions (States, Provinces, Territories, Prefectures, US DMAs, etc.)

Keep in mind that the smaller the geographic area, the less consistently accurate the segment will be. For Example: Accuracy of US Geographic Segments from broadband and cellular IPs: State (Subdivision)? 80% correct City? 38% correct Postal code? 21% correct. Therefore, will not create segments lower than the subdivision level.

Segments based on custom data

Tracking subscription plans, registration status, or any other custom parameter requires some additional work by your development team. This involves making a small change to your integration so that the additional information gets sent as part of each pageview request.

Once you complete this work, will use the key/value pair you are sending as extra data with your pageview events and build the custom audience segment into your dashboard.

The most important takeaway is that you need a method to find and get the data. The development work to identify users and add the segmentation code to your pages rests solely upon your team. As long as you have this segment defined somewhere else, and you have the ability to pull it out and put it into the pixel, you can track that segment in the dashboard.

Keep in mind that every unique value you want to track must be defined with a segment because cannot support wildcards.

Example workflows

An example customer workflow for setting up segments might look something like this:

  1. The segment is defined somewhere in your marketing stack, and an API call is made to that marketing platform to check whether or not the request is from an identified user.
  2. A cookie is set that identifies the user in the segment. (This often used to happen client-side, but for security reasons increasingly these types of calls are made server-side).
  3. If the user is part of the defined segment in the marketing stack, the frontend code will make a pageview call to with the requisite key/value pair.
  4. The segmented users will then be visible in the dashboard as different audience segments

Here’s a practical example of that workflow from a well-known marketing platform, Marketo, where our intent is to track users who are paid subscribers or not paid subscribers in

  1. A user visits the webpage. The server uses the user’s Marketo ID (stored in the “_mkto_track” cookie) to look up the user in the Marketo database.
  2. If the server finds a user, it will look at the user’s data and see if they are a paid subscriber or not. If they are a paid subscriber, you will create a cookie called “paid_subscriber” and set it to true.
  3. When the request returns to the website, the client-side JavaScript checks that cookie. If that cookie exists, it uses the JavaScript library to send a pageview call to with the extra data attached (see sample code below). 
  4. Our system will read the pixel with extra data attached and categorize the view appropriately.

Example code

Here’s an example of what custom segment tracking code might look like for a user that is subscribed to a “basic” plan. This uses the recommended update defaults method:

window.PARSELY = window.PARSELY || {
 autotrack: false,
 onReady: function() {
   data: {
    plan: "basic"

<!-- START Include -->
<!-- ...insert the parsely tracker code here... -->
<!-- END Include -->


Any segmentation code must be placed before your standard Parsely tracking snippet.

In the example above, note that in the call to PARSELY.updateDefaults, we provide an object like this:

  data: {
   plan: "<name of plan>"

You must pass a data object that matches this shape. Within the data object, you can use whatever key/value strings best describe your business logic. For example, the following would also be valid:

  data: {
   user_type: "anonymous",
   content_type: "free"

Booleans may also be used, as in this example:

  data: {
   Logged_in: true,

In a real integration, the value of each data property will be set by your business logic. This means that any value you intend to use for segmentation must be available client-side by the time the tracker loads. It’s also important to consistently handle null values; in the example above, if a current user isn’t subscribed to any plan, you would have to choose between setting data.plan to null or simply skipping the call to PARSELY.updateDefaults.

Custom audience segments integration using Google Tag Manager (GTM)

If you used Google Tag Manager (GTM) to implement the tracker, audience segments can be implemented by following the instructions in step 6 of the “How to set up” section.

If you don’t see the Custom Audience Segments section you may be on an older version of the tag template. To update, navigate to the Templates tab on the left side of your Tag Manager container UI and click the update icon next to the Tracker tag template.

Valid values

Value strings are treated as case-sensitive by default.

Segmentation values should represent general categories of users. Sending personal information like names or email addresses is ineffective for creating segments, and a violation of our terms of use.

Verification and debugging

To verify that your segmentation code is working as intended, you can inspect the raw pageview events that are sent to

Within the “Query String Parameters” section of the pageview request, you’ll want to verify that the data property contains the correct value given your current segmentation status (whether signed-in, registered as a subscriber, etc.). Alternatively, you can also access that field by typing into the developer console.

It’s worth testing each scenario that your business logic should handle, including the case when the custom data is not available.

Segments in your dashboard

Once you’ve made the integration changes to send custom data and verified the requests as described above the team will enable segments in your dashboard. You’ll need to provide a list of key/value pairs as well as the name for each segment. Leave a comment on the custom audience segments task in your Asana integration project or email this info to Depending on your specifications, segments will be added to individual dashboards or on the network level allowing you to view aggregate data for all your tracked sites.

Last updated: August 16, 2023