Context

[ianstormtaylor]

Forgot about the need for this one, but there's a field for all API calls to our API called context. And one of the things we do is that for each library we include library-specific information there. For Magento we'd want to include:

context: {
  library: {
    name: 'analytics-magento',
    version: '0.0.1'
  }
}

We use that internally for metrics and to do smart automating things in support and such. We'd want to add this automatically to all client-side and server-side calls from the extension

In analytics.js the third parameter to most of the calls is the context:

analytics.track('event', {/* properties */}, {
  library: {
    name: 'analytics-magento',
    version: '0.0.1'
  }
});

In PHP it takes a context key in the top-level array:

array(
  "userId" => "019mr8mf4r",
  "event" => "Purchased Item",
  "properties" => array(
    "revenue" => 39.95,
    "shipping" => "2-day"
  ),
  "context" => array(
    "library" => array(
      "name" => "analytics-magento",
      "version" => "0.0.1"
    )
  )
)

[astorm]

Adding this as a third parameter to the track calls.

analytics.track("Wishlisted Product",
segment_analytics_addedtowishlist.params,
{"library":{"name":"analytics-magento","version":"0.0.1"}}    );

I'm a little unclear how how this should be added to page/identity/alias -- especially page since a two parameter call to page is a category request?

window.analytics.page(segment_analytics_page.full_category_name, segment_analytics_page.page_title);      

I'm also a little unclear on why you included a PHP array above that has a top level key context after showing the syntax for track is to pass the context in as a third item.

[ianstormtaylor]

Sure thing, we're actually just about to change the way this works for the Javascript library, so here's an updated version for the new API in Javascript only:

analytics.track('event', { property: 'something' }, {
  context: {
    library: {
      name: 'analytics-magento',
      version: '0.0.1'
    }
  }
});

The difference is that the options object is now nested (to provide for other potential API features other than context). This changed should be merged tomorrow or the next day, so we can make it now.

The other methods have their options object like so:

analytics.identify(userId, traits, options);
analytics.track(event, properties, options);
analytics.page(category, name, properties, options);
analytics.group(groupId, traits, options);
analytics.alias(userId, options);

So each time you see options, we should replace that with:

{
  context: {
    library: {
      name: 'analytics-magento',
      version: '0.0.1'
    }
  }
}

[ianstormtaylor]

The PHP library (and other libraries) are structured slightly differently, since they are stateless. They have all of their parameters as keys in a top-level array, like so:

Analytics::track(array(
  "userId" => "user",
  "event" => "event",
  "properties" => array(),
  "context" => array(
    "library" => array(
      "name" => "analytics-magento",
      "version" => "0.0.1"
    )
  )
));

And all of the PHP calls have the same top-level structure, so they would all put context in an extra, top-level key.

Does that make sense? Let me know if you have questions.

[ianstormtaylor]

Actually, I just realized, ignore the PHP stuff.

I think you're exposing a Magento model that wraps our PHP library? I just realized we shouldn't actually be exposing a proper PHP API, we should expose it in a way that just adds the calls they make there to the page, like we do with WordPress: https://github.com/segmentio/analytics-wordpress/blob/master/analytics-wordpress.php#L150

[astorm]

Ian thanks. One last question — what should I be passing in on the page calls that aren't categories? i.e., a regular page call looks like

analytics.page('Some Page');

Do I just do this?

analytics.page('Some Page',null,null,{...context...});

Or will that be interpreted as the category form

analytics.page(category, name, properties, options);

[ianstormtaylor]

For those ones, the API will handle overloading for you if you want, so for example:

analytics.page(name, properties, options);

Works fine. But the nulls also work if that's clearer for you. Only reason properties is required there is because options is also an object, so we can't tell them apart.

Does that make sense?

[astorm]

Yup, makes sense. All calls (identify, track, page, alias, we're not using group) should have the context object now.