From b6a9ae8ae304a105fbb08815104a92801852ed91 Mon Sep 17 00:00:00 2001 From: pete gamache Date: Mon, 4 Apr 2016 08:54:10 -0400 Subject: [PATCH 1/6] added `track` and `screen` handlers; updated handlers for new Appcues SDK --- lib/index.js | 70 +++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 66 insertions(+), 4 deletions(-) diff --git a/lib/index.js b/lib/index.js index 765106d..21ee2bd 100644 --- a/lib/index.js +++ b/lib/index.js @@ -63,13 +63,47 @@ Appcues.prototype.load = function(callback) { /** * Page. * - * http://appcues.com/docs#start + * http://appcues.com/docs#page * * @api public + * @param {Page} page */ -Appcues.prototype.page = function() { - window.Appcues.start(); +Appcues.prototype.page = function(page) { + if (!this.loaded()) { + console.log('Appcues is not loaded'); + return; + } + + if (window.Appcues.page) { + window.Appcues.page(page.name(), page.properties()); + } else { + // Legacy SDK + window.Appcues.start(); + } +}; + +/** + * Screen. + * + * http://appcues.com/docs#screen + * + * @api public + * @param {Screen} screen + */ + +Appcues.prototype.screen = function(screen) { + if (!this.loaded()) { + console.log('Appcues is not loaded'); + return; + } + + if (window.Appcues.screen) { + window.Appcues.screen(screen.name(), screen.properties()); + } else { + // Legacy SDK + window.Appcues.start(); + } }; /** @@ -82,5 +116,33 @@ Appcues.prototype.page = function() { */ Appcues.prototype.identify = function(identify) { - window.Appcues.identify(identify.userId(), identify.traits()); + if (!this.loaded()) { + console.log('Appcues is not loaded'); + return; + } + + if (window.Appcues.identify) { + window.Appcues.identify(identify.userId(), identify.traits()); + } +}; + +/** + * Track. + * + * http://appcues.com/docs#track + * + * @api public + * @param {Track} track + */ + +Appcues.prototype.track = function(track) { + if (!this.loaded()) { + console.log('Appcues is not loaded'); + return; + } + + if (window.Appcues.track) { + window.Appcues.track(track.event(), track.properties()); + } }; + From 5837c201005160ec90f58bed15b285f15c644fa3 Mon Sep 17 00:00:00 2001 From: pete gamache Date: Thu, 7 Apr 2016 15:17:29 -0400 Subject: [PATCH 2/6] removed screen; made track, identify, and page simple passthroughs --- lib/index.js | 53 +++------------------------------------------- test/index.test.js | 20 ++++++++++++----- 2 files changed, 18 insertions(+), 55 deletions(-) diff --git a/lib/index.js b/lib/index.js index 21ee2bd..8c7469b 100644 --- a/lib/index.js +++ b/lib/index.js @@ -70,40 +70,7 @@ Appcues.prototype.load = function(callback) { */ Appcues.prototype.page = function(page) { - if (!this.loaded()) { - console.log('Appcues is not loaded'); - return; - } - - if (window.Appcues.page) { - window.Appcues.page(page.name(), page.properties()); - } else { - // Legacy SDK - window.Appcues.start(); - } -}; - -/** - * Screen. - * - * http://appcues.com/docs#screen - * - * @api public - * @param {Screen} screen - */ - -Appcues.prototype.screen = function(screen) { - if (!this.loaded()) { - console.log('Appcues is not loaded'); - return; - } - - if (window.Appcues.screen) { - window.Appcues.screen(screen.name(), screen.properties()); - } else { - // Legacy SDK - window.Appcues.start(); - } + window.Appcues.page(page.name(), page.properties()); }; /** @@ -116,14 +83,7 @@ Appcues.prototype.screen = function(screen) { */ Appcues.prototype.identify = function(identify) { - if (!this.loaded()) { - console.log('Appcues is not loaded'); - return; - } - - if (window.Appcues.identify) { - window.Appcues.identify(identify.userId(), identify.traits()); - } + window.Appcues.identify(identify.userId(), identify.traits()); }; /** @@ -136,13 +96,6 @@ Appcues.prototype.identify = function(identify) { */ Appcues.prototype.track = function(track) { - if (!this.loaded()) { - console.log('Appcues is not loaded'); - return; - } - - if (window.Appcues.track) { - window.Appcues.track(track.event(), track.properties()); - } + window.Appcues.track(track.event(), track.properties()); }; diff --git a/test/index.test.js b/test/index.test.js index b8f6c3d..93b17c9 100644 --- a/test/index.test.js +++ b/test/index.test.js @@ -76,13 +76,23 @@ describe('Appcues', function() { describe('#page', function() { beforeEach(function() { - analytics.stub(window.Appcues, 'start'); + analytics.stub(window.Appcues, 'page'); }); - it('should proxy to Appcues.start()', function() { - analytics.didNotCall(window.Appcues.start); - analytics.page('Pricing'); - analytics.called(window.Appcues.start); + it('should call Appcues.page', function() { + analytics.page('some page', { someAttr: true }); + analytics.called(window.Appcues.page, 'some page'); + }); + }); + + describe('#track', function() { + beforeEach(function() { + analytics.stub(window.Appcues, 'track'); + }); + + it('should send name and attributes', function() { + analytics.track('some event', { someAttr: true }); + analytics.called(window.Appcues.track, 'some event', { someAttr: true }); }); }); From 9225771584ef643480d8752b1ee2478d80d5ce7d Mon Sep 17 00:00:00 2001 From: pete gamache Date: Mon, 11 Apr 2016 07:59:41 -0400 Subject: [PATCH 3/6] added our Segment integration documentation --- DOCS.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 DOCS.md diff --git a/DOCS.md b/DOCS.md new file mode 100644 index 0000000..fada286 --- /dev/null +++ b/DOCS.md @@ -0,0 +1,73 @@ +Create personalized user onboarding flows without changing any code +that will improve your product's adoption and retention rates. +[Visit Website](http://appcues.com) + +Our Appcues integration code is [open-source on +GitHub](https://github.com/appcues/analytics.js-integration-appcues) +if you want to check it out. + +## Getting Started + +To install Appcues via Segment, all you have to do is add your Appcues ID +and API key +(found on your [Appcues account page](https://my.appcues.com/account)) +to your Segment integrations dashboard. + +## API + +### Identify + +When you `identify` on `analytics.js`, we call `Appcues.identify`. This +is the preferred method of using and targeting on user properties. + +To get the most out of Appcues, you’ll want to send as much user data +as possible in the identify call. Properties are used to target experiences +to specific users and personalize content. Most Appcues customers send +properties that fall into a few groups: + +* Properties to target based on broad classifications such as `role` + or `userType` +* Properties to personalize Appcues content such as `name`, `firstName` + or `company` +* Properties to target based on user lifecycle such as `createdAt` (date) + or usage metrics such as `numTasksComplete` + +### Track + +Calls to `analytics.track` invoke `Appcues.track` as well. This will +send event data to the Appcues platform, where it can be used for future +content triggering. + +### Page + +Appcues will check to see if a user qualifies for an experience every time +the page changes. When you first call `page` using `analytics.js`, +`Appcues.start` checks if there are any current flows for the user and +loads them if necessary. + +## Appcues Features + +### Whitelisted Domains + +By default, Appcues will target based on the path of the URL. So if we created an Appcues experience and targeted it to /integrations, it would appear wherever the embed script is installed with that URL path, like appcues.com/integrations and my.appcues.com/integrations. If your analytics.js script is installed on multiple domains (e.g. your marketing site and your web app), you’ll want to use Appcues whitelisted domains when targeting your experience. + +### Sending Appcues events via Segment + +Want to read Appcues events in your 3rd party analytics or marketing automation tool? Appcues supports sending events to other tools on the Segment platform. These events will be sent as track calls to the other integrations you’ve turned on. + +To enable this feature, go to the Integrations Settings in Appcues and click “Activate” under the Segment integration. + +## Receiving external data via Segment + +Appcues can accept data from other Segment partners too, via our +server-side integration. This way, you can keep Appcues in sync with +user properties and events without needing the data to originate from +your website where Appcues is running. + +## Settings + +Segment lets you change these settings on the Integrations page, without having to touch any code. + +Appcues Id +Appcues API key + From 03fa4d53a9dfa87ca2e5914490e05c5c7dc7803a Mon Sep 17 00:00:00 2001 From: pete gamache Date: Thu, 14 Apr 2016 09:03:21 -0400 Subject: [PATCH 4/6] improved docs --- DOCS.md | 67 +++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 46 insertions(+), 21 deletions(-) diff --git a/DOCS.md b/DOCS.md index fada286..02057a4 100644 --- a/DOCS.md +++ b/DOCS.md @@ -8,12 +8,40 @@ if you want to check it out. ## Getting Started -To install Appcues via Segment, all you have to do is add your Appcues ID -and API key +To install Appcues via Segment, add your Appcues ID and API key (found on your [Appcues account page](https://my.appcues.com/account)) to your Segment integrations dashboard. -## API + +## JS and Server-side Integrations + +Appcues provides two Segment integrations. + +The first, our JavaScript integration with Segment's `analytics.js`, +is the traditional way to use Appcues as part of the Segment platform. +Calls to `analytics.identify` are used to indicate user properties, +and `analytics.page` or `analytics.track` will send events to the +Appcues API. + +Separately, Appcues offers a server-side integration with Segment, +which is useful if you'd like to bring in user profile or event data +from another Segment partner service. The server-side integration +may be used simultaneously with the JS integration. In many cases, +this is preferable to routing all data through the JS integration. + +The user profile and event data received through Appcues' +server-side Segment integration can be used to segment +and target Appcues flows, just like data received from the JS +integration. + +For example, using the server-side integration, customer profile and +event data could be directed from a CRM tool into the Appcues platform. +This data could then be used for content targeting and user +segmentation in the Appcues content editor, alongside data from +our `analytics.js` integration. + + +## JavaScript API ### Identify @@ -45,29 +73,26 @@ the page changes. When you first call `page` using `analytics.js`, `Appcues.start` checks if there are any current flows for the user and loads them if necessary. + ## Appcues Features ### Whitelisted Domains -By default, Appcues will target based on the path of the URL. So if we created an Appcues experience and targeted it to /integrations, it would appear wherever the embed script is installed with that URL path, like appcues.com/integrations and my.appcues.com/integrations. If your analytics.js script is installed on multiple domains (e.g. your marketing site and your web app), you’ll want to use Appcues whitelisted domains when targeting your experience. - -### Sending Appcues events via Segment - -Want to read Appcues events in your 3rd party analytics or marketing automation tool? Appcues supports sending events to other tools on the Segment platform. These events will be sent as track calls to the other integrations you’ve turned on. - -To enable this feature, go to the Integrations Settings in Appcues and click “Activate” under the Segment integration. - -## Receiving external data via Segment - -Appcues can accept data from other Segment partners too, via our -server-side integration. This way, you can keep Appcues in sync with -user properties and events without needing the data to originate from -your website where Appcues is running. +By default, Appcues will target based on the path of the URL. So if we +created an Appcues experience and targeted it to `/integrations`, +it would appear wherever the embed script is installed with that URL path, +like appcues.com/integrations and my.appcues.com/integrations. If your +analytics.js script is installed on multiple domains (e.g. your marketing +site and your web app), you’ll want to use Appcues whitelisted domains when +targeting your experience. -## Settings +### Sending Appcues events to other Segment partner services -Segment lets you change these settings on the Integrations page, without having to touch any code. +Want to read Appcues events in your 3rd party analytics or marketing +automation tool? Appcues supports sending events to other tools on the +Segment platform. These events will be sent as track calls to the other +integrations you’ve turned on. -Appcues Id -Appcues API key +To enable this feature, go to the Integrations Settings in Appcues and +click “Activate” under the Segment integration. From 0718a9ec790125835f47553cb78ba26ab11545ca Mon Sep 17 00:00:00 2001 From: pete gamache Date: Mon, 25 Apr 2016 12:19:55 -0400 Subject: [PATCH 5/6] docs update --- DOCS.md | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/DOCS.md b/DOCS.md index 02057a4..1505ca6 100644 --- a/DOCS.md +++ b/DOCS.md @@ -24,10 +24,15 @@ and `analytics.page` or `analytics.track` will send events to the Appcues API. Separately, Appcues offers a server-side integration with Segment, -which is useful if you'd like to bring in user profile or event data -from another Segment partner service. The server-side integration -may be used simultaneously with the JS integration. In many cases, -this is preferable to routing all data through the JS integration. +which is useful if you'd like to send user profile or event data to +Appcues from another Segment partner service. (Note that this is +different from [Segment Sources](https://segment.com/sources), which +allows you to bring multiple sources of Segment data together in your +own data warehouse.) + +The server-side integration may be used simultaneously with the JS +integration. In many cases, this is preferable to routing all data +through the JS integration. The user profile and event data received through Appcues' server-side Segment integration can be used to segment @@ -91,7 +96,21 @@ targeting your experience. Want to read Appcues events in your 3rd party analytics or marketing automation tool? Appcues supports sending events to other tools on the Segment platform. These events will be sent as track calls to the other -integrations you’ve turned on. +integrations you’ve turned on. A partial list of Appcues content +lifecycle events that can be tracked: + +* `flow_shown` +* `flow_skipped` +* `flow_finished` +* `flow_form_submission` +* `form_field_submission` +* `step_activated` +* `hotspots_shown` +* `hotspots_skipped` +* `hotspots_completed` +* `hotspot_activated` +* `coachmarks_shown` +* `coachmarks_completed` To enable this feature, go to the Integrations Settings in Appcues and click “Activate” under the Segment integration. From 0b950706d3ab6bc85822731fb1223fa59e1b6fa5 Mon Sep 17 00:00:00 2001 From: Ray Di Ciaccio Date: Tue, 6 Sep 2016 17:37:28 -0400 Subject: [PATCH 6/6] Test that attributes are passed into Appcues.page call. --- test/index.test.js | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/test/index.test.js b/test/index.test.js index 2116cd2..39ce39e 100644 --- a/test/index.test.js +++ b/test/index.test.js @@ -82,6 +82,10 @@ describe('Appcues', function() { it('should call Appcues.page', function() { analytics.page('some page', { someAttr: true }); analytics.called(window.Appcues.page, 'some page'); + // No way to assert an argument "match", and analytics.page includes + // other properties automatically, so manually checking the second + // arg to Appcues.page includes the `someAttr` value. + analytics.assert(window.Appcues.page.args[0][1].someAttr === true); }); });