Parsely Destination

Parse.ly provides web analyses and content optimization for online publishers by partnering with them to provide clear audience insights through intuitive analytics.

This document was last updated on November 8th, 2018. If you notice any gaps, out-dated information or simply want to leave some feedback to help us improve our documentation, please let us know!

Getting Started

The first step is to make sure Parsely supports the source type and connection mode you’ve chosen to implement. You can learn more about what dictates the connection modes we support here.

WebMobileServer
📱 Device-mode
☁️ Cloud-mode
  1. From your Segment UI’s Destinations page click on “Add Destination”.
  2. Search for “Parsely” within the Destinations Catalog and confirm the Source you’d like to connect to.
  3. Enter your Domain and enable the destination in Segment. (To enable this destination, you use your Parsely website domain as your API key.)
  4. We’ll automatically start recording data.

When Parse.ly is enabled in Segment, our CDN updates within 45 minutes. Parse.ly’s javascript is asynchronously loaded onto your page, so remember to remove the Parse.ly snippet from your page.

Parsely is substantially more useful when you implement JSON-LD metadata across your website as described here.

Page

By default, unless you are using Dynamic Tracking, Parse.ly automatically tracks pageviews in the background, so you do not need to track them separately with Segment’s .page() method.

If you are using dynamic tracking, you must explicitly let us know in your integration settings. If this setting is enabled, we will disable Parse.ly’s autotracking functionality and begin sending their API pageview events only in response to analytics.page() events.

Note: You can only track pageviews if you are using the Parsely destination with our Javascript Analytics.js library, and not using our server side integration with Parse.ly.

Identify

If you haven’t had a chance to review our spec, please take a look to understand what the Identify method does. An example call would look like:

analytics.identify('ze8rt1u89', {
  name: 'Zaphod Beeblebrox',
  gender: 'Male',
  email: 'Zaphod@hotmail.com',
  phone: '1-401-826-4421',
  address: {
    city: 'San Francisco',
    state: 'Ca',
    postalCode: '94107'
  }
});

Track

You must adhere to our video tracking spec (and have video tracking enabled in Parse.ly) in order to use this functionality.

Video tracking is possible with either web or server sources.

Group

If you haven’t had a chance to review our spec, please take a look to understand what the Group method does. An example call would look like:

analytics.group("0e8c78ea9d97a7b8185e8632", {
  name: "Initech",
  industry: "Technology",
  employees: 329,
  plan: "enterprise",
  "total billed": 830
});

Alias

If you haven’t had a chance to review our spec, please take a look to understand what the Alias method does. An example call would look like:

analytics.alias("507f191e81");

Mapping custom properties to semantic Parsely properties

If you’d like to map certain semantic Parse.ly properties to your own custom properties (ones that do not abide by our page spec, you can define your mappings in your Segment destination settings! You can put the name of your Segment property on the left and the Parse.ly property on the right hand side.

We currently support mapping the following Parse.ly properties (make sure you spell these correctly on the right hand side of this setting!):

  • articleSection
  • thumbnailUrl
  • dateCreated
  • headline
  • keywords
  • creator
  • url

Note: This feature only works if you also have enabled Enable In-Pixel Metadata and Enable Dynamic Tracking.

Video Content Started

When a user starts playback of a video, you should use our Video Content Started event. We will map the properties from the Video Content Started event to the following Parse.ly video metadata fields:

Parsely ParameterSegment PropertyData Type
videoIdproperties.assetIdString
metadata.titleproperties.titleString
metadata.image_urlcontext.integrations.Parsely.imageUrlString
metadata.pub_date_tmspproperties.airdateString
metadata.sectionproperties.genreString
metadata.authorsproperties.publisherString
metadata.tagscontext.integrations.Parsely.tagsArray
urlOveridecontext.page.urlString

Because tags and imageUrl are not recognized as properties of a standard Video Content Started event, we ask that you pass those as integration specific options.

Example

analytics.track('Video Content Started', {
    assetId: '12345',
    title: 'Magic Eye: The optical illusion, explained',
    airdate: 'Tue May 16 2017 17:02:05 GMT-0700 (PDT)',
    genre: 'Science',
    publisher: 'Vox'
    }, {
    integrations: {
        Parsely: {
            imageUrl: 'https://cdn.cloudfront.com/images/image_file.png'
            tags: ['tags', 'go', 'here']
        }
    }
});

Video Playback Paused

When a user pauses playback of a video, you should use our Video Playback Paused event. Assuming the Pause event happens after a Video Content Started event, we will automatically map the video metadata for you.

Video Playback Interrupted

When a playback of a video is interrupted, you should use our Video Playback Interrupted event. This event just takes an assetId and maps to Parse.ly’s reset method (documentation here).

Note: this event is only relevant for web tracking. Our server side integration does not support this event.

Parsely ParameterSegment PropertyData Type
videoIdproperties.assetIdString

Example

analytics.track('Video Playback Paused', {
    assetId: '12345'
    // Feel free to pass as many other properties as you like here.
    // This is just an example showing what Parse.ly will receive.
});

Video Content Playing

(Note: this event is only required for server side tracking)

When using Parse.ly on the web using our Javascript SDK, video heartbeats are captured by their SDK automatically. However, if you are using this destination with a Server side source, you must pass heartbeat events manually using our Video Content Playing event.

Important: These events must be sent in 10 second increments.

The only required property is the video’s assetId.

Example:

analytics.track({
  userId: '019mr8mf4r',
  event: 'Video Content Playing',
  properties: {
    sessionId: '12345',
    assetId: '0129370',
    podId: 'segA',
    title: 'Interview with Tony Robbins',
    description: 'short description',
    keywords: ['entrepreneurship', 'motivation'],
    season: '2',
    episode: '177',
    genre: 'entrepreneurship',
    program: 'Tim Ferris Show',
    publisher: 'Tim Ferris',
    position: 20,
    totalLength: 360,
    channel: 'espn',
    fullEpisode: true,
    livestream: false,
    airdate: '1991-08-13'
  }
});

Video Content Completed

This event is only required for server side tracking.

To track the completion of a video, please use our Video Content Completed event.

Please ensure you are sending at minimum, assetId, totalLength, and position as properties.

Example:

analytics.track({
  userId: '019mr8mf4r',
  event: 'Video Content Completed',
  properties: {
    sessionId: '12345',
    assetId: '0129370',
    podId: 'segA',
    title: 'Interview with Tony Robbins',
    description: 'short description',
    keywords: ['entrepreneurship', 'motivation'],
    season: '2',
    episode: '177',
    genre: 'entrepreneurship',
    program: 'Tim Ferris Show',
    publisher: 'Tim Ferris',
    position: 20,
    totalLength: 360,
    channel: 'espn',
    fullEpisode: true,
    livestream: false,
    airdate: '1991-08-13'
  }
});

Track URL

The destination does not currently support Parsely’s trackURL method. Please contact us if this is important to you.


Personas

You can send computed traits and audiences generated through Segment Personas to this destination as a user property. To learn more about Personas, reach out for a demo.

For user-property destinations, an identify call will be sent to the destination for each user being added and removed. The property name will be the snake_cased version of the audience name you provide with a true/false value. For example, when a user first completes an order in the last 30 days, we will send an identify call with the property order_completed_last_30days: true, and when this user no longer satisfies we will set that value to false.

When the audience is first created an identify call is sent for every user in the audience. Subsequent syncs will only send updates for those users which were added or removed since the last sync.

Settings

Segment lets you change these destination settings via your Segment dashboard without having to touch any code.

Domain

Parsely’s required API Key should be your website domain. (ie. segment.com)

Map Custom Page Properties

Map your custom .page() property names on the left and semantic Parsely properties on the right.

Enable Dynamic Tracking

If you enable Dynamic Tracking, Segment will disable Parsely autotracking and instead explicitly proxy your page() calls to Parsely. This feature is recommended if you want Segment to pass additional pageview metadata collected with your .page() properties through to Parsely. See here for more information.

Enable In-Pixel Metadata

If you enable In-Pixel Metadata, Segment will map page properties to Parsely’s metadata format, allowing you to eschew their out-of-band metadata crawling. This has tradeoffs and is not the recommended approach— please be sure to check with your Parsely rep prior to enabling this setting. Requires Dynamic Tracking to be set to true.

Track Events

Parsely can track custom events, but does not surface these events in their Dashboard or UI. If you’d like your Segment track() calls to flow to Parsely’s Raw Data Pipeline product, enable this setting. See here for more information.

Adding Parsely to the integrations object

To add Parsely to the integrations JSON object (for example, to filter data from a specific source), use one of the 1 valid names for this integration:
  • Parsely


  • Questions? Need help? Contact us!
    Can we improve this doc?
    Email us: docs-feedback@segment.com!