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-based
☁️ Cloud-based
  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 5-10 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 there is no need to worry about integrating with this functionality via 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: tracking pageviews is only possible if you are using this integration via our Javascript SDK: analytics.js (not via our server side integration with Parse.ly).

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.

Track

We integrate with Parse.ly’s video tracking capabilities. via the use of our .track() method. 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.

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 via our Javascript SDK, video heartbeats are captured by their SDK automatically. If you are using this integration via a Server side source however, you will need to pass heartbeat events manually via the use of our Video Content Playing event.

Important: please ensure you are sending these events in 10 second increments.

The only required property that we ask you pass 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

(Note: 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.

Supported Sources and Connection Modes

WebMobileServer
📱 Device-based
☁️ Cloud-based

To learn more about about Connection Modes and what dictates which we support, see here.

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.


If you have any questions, or see anywhere we can improve our documentation, please let us know!