segmentio / analytics.js-integrations

Monorepo housing Segment's analytics.js integrations

Analytics.js Integrations

Introduction

This repo stores the majority of the analytics.js integrations that Segment currently supports. It is organized as a monorepo with each individual integration packaged and deployed as their own npm modules.

Getting Started

To start contributing, please ensure you have the following installed on your local machine:

• yarn
• node

Once these pre-requisites are met, feel free to clone the repo locally and install the required dependencies:

git clone https://github.com/segmentio/analytics.js-integrations && cd analytics.js-integrations
yarn

Contributing

All individual integrations are stored in the integrations/ directory. We recommend navigating into the individual integration you are contributing to in your terminal rather than working from the root directory:

cd integrations/<INTEGRATION_NAME>

Breaking Changes

Please note, there is currently no way for user's of these integrations to choose specific versions. Therefore, all changes must always be fully backwards compatible. If a change is breaking it will not be considered.

Adding Dependencies

If you need to add an external dependency to an integration, please ensure you add it within the integration directory, not the root directory. That being said, please keep in mind that these integrations are run client side. Please only add external dependencies if it is critical to your code changes.

Running Tests

Each integration directory has an npm script called test that you can use to easily run the unit tests with via yarn test.

Test Locally

To test changes locally you can run:

yarn --cwd tester install
yarn dev

This will open the local development environment. To test a particular destination, enter a writeKey that has the destination connected, and the tool will load Analytics.js with the local version of the destinations connected, and the settings for the source. After the first load, you can referesh the page without having to load the writeKey each time.

If you want to test a new destination or a new settings parameter, you can override the settings using the integrated JSON editor. To fire track, page, etc. calls, you can use the Chrome DevTools and fire events using analytics.track( .... ) etc.

Code Formatting

This project uses eslint to ensure uniform code formatting standards are maintained. You can see the specific eslint config in the root .eslintrc file. A pre-commit hook is used to help automate this process for you.

Pull Requests

Please make sure your PR includes the new version in package.json as well as an update to the integration's HISTORY.md file describing the change.

Releasing

All releases are handled by Segment engineers. Releases will be managed after a change has been approved and merged.

analytics.js-integrations's Issues

Facebook event InitiateCheckout is missing `content_type` parameter

The InitiateCheckout event here is missing the content_type parameter used in other events here.

Facebook highlights this as a required parameter on their integration:

[nielsen-dcr] New test issue

Migrated from #15 by @CarlosMecha

Fix me! I'm broken!

[nielsen-dcr] This is the test2

Migrated from #14 by @CarlosMecha

Fix me!

[nielsen-dcr] Pull Request #16: Update Readme TEST

Migrated from #16 by @CarlosMecha

This is so important.

[nielsen-dcr] Pull Request #18: Add test file for test Pull Request

Migrated from #18 by @CarlosMecha

Please ignore me.

[appboy] integration snippet needs update (or replacement with npm require)

Migrated from #33 by @froodian

The current integration is using a loading snippet at https://github.com/segment-integrations/analytics.js-integration-appboy/blob/fd6b5cdd65398c6cdaddb30d4f952e5a5de35384/lib/index.js#L124 that's somewhat different from the default one at https://github.com/Appboy/appboy-web-sdk#getting-started, and it's causing loading failures (js errors) in some environments. The issue is that it explicitly gives appboy and appboyQueue the window namespace (window.appboy, window.appboyQueue), but pushes to the appboyQueue in the global namespace. There were some updates on the Braze end around this snippet a while back to improve this situation, so it's possible it's simply outdated.

A larger point I want to raise here though is that this entire snippet with the appboyQueue structure was designed to be put in the <head> of an HTML page for naive clients in a raw html environment, and exists to handle method calls that happen before the script has loaded. Given that in this integration, the script is instead loaded with this.load('v2', function() {, that snippet could be removed entirely and all methods on appboy simply called within the callback function.

Even simpler in fact, given the npm environment, would be to do npm install --save-dev appboy-web-sdk, var appboy = require('appboy-web-sdk'); and then you can just immediately call appboy.initialize and start calling methods from there. I'm not sure how you'd want to handle your v1 and v2 support however.

Given that there are a few different options here, I leave it to you to choose which one you want in your codebase, but that mismatch between window.appboyQueue= and appboyQueue.push should be rectified somehow, and I can tell you that internally the SDK draws from appboyQueue if it exists (and ignores it gracefully if it doesn't), so this code should either define and push to that, or omit it entirely.

Thanks!

[hubspot] Segment does not load the forms SDK if the Hubspot Analytics file fails to load

Hello,

My ad/tracking blocker (uBlock in Firefox) blocks the load of the Hubspot analytics file, as expected.
uBlock does not, however, block the load of the Hubspot Forms SDK when loaded directly.

Unfortunately, when segments fails to load the Hubspot analytics file, it does not try to load the forms SDK, and never calls the 'ready' callback. Therefore my Hubspot form does not show up.

(My workaround for now is to load the Hubspot Forms SDK myself rather than through Segment, but I'd like Segment to load the Forms SDK even when the other file has failed)

Best regards,
Laurent

[facebook-pixel] Pull Request #19: tests and add order id

Migrated from #19 by @jamalc

Decided to start over and do this the right way :-)

Recently, FB has requested this data from us as part of the Purchase Event. I thought I would try to add it instead of creating a custom event.

cc'ing @wcjohnson11 to verify this should be added!

[moengage] Pull Request #7: add destroy session condition in track calls

Migrated from #7 by @durgani

This condition to call the integration's destroy session method needs to exist in track calls especially if they are invoked prior to identify (where the condition already exists).

[facebook-pixel] error loading "Facebook Pixel" error="Error: script error "http://connect.facebook.net/en_US/fbevents.js"

Migrated from #40 by @Macbit

analytics:integration:facebook-pixel error loading "Facebook Pixel" error="Error: script error "http://connect.facebook.net/en_US/fbevents.js" at HTMLScriptElement.<anonymous> (https://cdn.segment.com/analytics.js/v1/wUgzMSmoJCAqPDNtJ5BfDTzRFWDduzcP/analytics.min.js:10:3537)" +18ms

[hubspot] Hubspot adds url parameters making them invalid

Migrated from #17 by @slowtokyo

I am having the issue as detailed in here: segmentio/analytics.js#504 when I try to add a url parameter to a query string hubspot puts its queries in front of the existing queries thereby creating an invalid URL. I have found a way around this that doesn't impact my analytics, but shouldn't the Hubspot query strings be appended to the end of any existing query strings?

The URL I want to create:
https://foo.bar.co/#/register?__hstc=6222316.1d2b332e80357701bf2ef394e3a88e1b.1508536177681.1521725761504.1521729618139.158&__hssc=6222316.4.1521729618139&__hsfp=1692073022&plan=professional

The URL that I get:
https://foo.bar.co/?__hstc=6222316.1d2b332e80357701bf2ef394e3a88e1b.1508536177681.1521725761504.1521729618139.158&__hssc=6222316.11.1521729618139&__hsfp=1692073022#/register?plan=professional

[appboy] Pull Request #31: Queue up logCustomEvent until in-app messaging is ready

Migrated from #31 by @ucarion

This PR ensures that calls to logCustomEvent won't happen until the appropriate in-app messaging is ready.

With this PR, we'll keep track of whether we are currently downloading in-app messaging. If we ever are, we queue up calls to logCustomEvent; once in-app messaging is ready, we'll flush that queue.

This change required changing our tests to hook into the internal _onMessagingReady method. This is non-ideal, but I can think of no easier way to have tests synchronize with Appboy's internal events system.

Note: The above explanation applies to logPurchase as well.

Closes #25.

[nielsen-dcr] Pull Request #13: This is a test PR

Migrated from #13 by @CarlosMecha

Add stuff

[livechat] integration doesn't work with new LiveChat widget

Migrated from #7 by @MichalPaszowski

Hello!
It seems that your integration doesn't work with our new chat widget.
In the new widget, we do not use these globals: LC_Invite and __lc_lang. If you remove that dependency from your code, everything should work because we didn't make any breaking changes in our chat widget API ( at least in documented methods ).

Regards, Michal

[woopra] Flatten objects

Migrated from #3 by @jpknegtel

Tried to pass an address object however this is can not be translated into seperate object into woopra.

[object Object] is what is seen in woopra under user address field.

This is what is passed from Segment:
address: {
city: 'Amsterdam',
country: 'NL',
county: 'Noord-Holland',
housenumber: '',
postalcode: '1032 HP',
street: ''
},

** taken out as personal info.

Should we just not use objects?

[facebook-pixel] "Product List Viewed" not writing product_ids to FB correctly

Migrated from #30 by @skyfallsin

Ref: https://github.com/segment-integrations/analytics.js-integration-facebook-pixel/blob/master/lib/index.js#L134

The product_ids are not getting dispatched to FB properly, and instead the category is being sent.

Here's the spec on the FB side (Scroll down to View Category)
https://developers.facebook.com/docs/marketing-api/dynamic-product-ads/product-audiences/v2.8

`make` command fails

Hi, I'm trying to test locally and I followed what the CONTRIBUTING.md guide:

Then after forking analytics.js-integrations just cd into the folder and run make:

$ cd analytics.js-integrations
$ make

But I've searched the repo and there is no makefile:

➜  analytics.js-integrations git:(master) make
make: *** No targets specified and no makefile found.  Stop.

Am I missing something?

[nielsen-dcr] Pull Request #13: This is a test PR

Migrated from #13 by @CarlosMecha

Add stuff

[appboy] Support for doNotLoadFontAwesome

Migrated from #16 by @sean-roberts

Braze automatically loads font awesome if you do not set doNotLoadFontAwesome: false in the initialize call. We don't need it but don't have a hook to change that at this point.

[doubleclick-floodlight] Pull Request #13: Add support for dbm cookie match

Migrated from #13 by @ccnixon

Adds support for conditionally loading the Google Display & Video 360 cookie match pixel based on the user's settings.

Test 1

Bla bla bla

[appboy] Only call changeUser when userID exists

Migrated from #22 by @dwillislc

When an identify, orderCompleted, page or track call is made without an userID, the mapping file is still attempting to call changeUser. This is resulting in a non-fatal error in the console log:

I see in Segment's documentation that adding a userID is optional for both the Identify and Track call, so it would be great if we could add some conditional logic:

if (userId) {
  	window.appboy.changeUser(userId);
  }

Thanks much!

[facebook-pixel] add support for trackSingle

Migrated from #38 by @jaredmcdonald

it would be great to add support for making requests for specific pixels with fbq('trackSingle', 'PIXEL_ID', ...) to disambiguate a Segment-managed pixel from other pixels that might be on a page

see https://developers.facebook.com/ads/blog/post/2017/11/28/event-tracking-with-multiple-pixels-tracksingle/

[hubspot] How do I send the IP address from Segment to HubSpot?

Migrated from #14 by @chhuang

I can see the IP address under the context property but I'm not sure how to send it.

[appboy] Pull Request #37: Wrap suspect changeUser calls in try/catch

Migrated from #37 by @ucarion

It appears likely that calls to changeUser in this integration, aside from that of identify, are not doing anything for this integration.

In an effort to demonstrate that it is precisely these changeUser calls which raise errors in the integration, this PR wraps these calls in try/catch. If this causes a reduction in errors from the integration, as is expected, then a follow-up PR will remove the calls to changeUser altogether. Otherwise, this PR will be rolled back.

To clarify: this PR is not meant to create a final state for the integration.

JIRA: https://segment.atlassian.net/browse/GA-542

[nielsen-dcr] This is the test2

Migrated from #14 by @CarlosMecha

Fix me!

[nielsen-dcr] Pull Request #13: This is a test PR

Migrated from #13 by @CarlosMecha

Add stuff

[nielsen-dcr] Pull Request #16: Update Readme TEST

Migrated from #16 by @CarlosMecha

This is so important.

[facebook-pixel] Pull Request #37: allow disable autoConfig

Migrated from #37 by @muZk

The Facebook pixel will send button click and page metadata (such as data structured according to Opengraph or Schema.org formats) from your website to improve your ads delivery and measurement and automate your pixel setup - https://developers.facebook.com/docs/facebook-pixel/api-reference#automatic-configuration

So I added an option to disable it 👍

[appboy] Pull Request #38: Updating Braze SDK to latest minor version v2.2 | PLATFORM-3353

Migrated from #38 by @hankim813

Updating the braze SDK to pull the latest minor version. @anoonan can we not pin to just v2 major version so we don't need to hardcode update everytime they release a new minor update?

[appboy] Pull Request #19: Support Braze addAlias

Migrated from #19 by @cdmwebs

Braze allows a name and a label, but Segment's alias doesn't currently
accept additional properties. For now, it'll just use the label 'alias'.

https://www.braze.com/academy/Data_and_Analytics/#user-aliases
https://www.braze.com/documentation/Web/#aliasing-users

[nielsen-dcr] Fix me! I'm broken

Migrated from #20 by @CarlosMecha

This is a test issue, please ignore

Foo Bar

[nielsen-dcr] Pull Request #21: New test feature

Migrated from #21 by @CarlosMecha

This is a test Pull Request, please ignore

Foo Bar

[nielsen-dcr] This is the test2

Migrated from #14 by @CarlosMecha

Fix me!

[nielsen-dcr] This is the test2

Migrated from #14 by @CarlosMecha

Fix me!

[appboy] Pull Request #25: If a message download is in-progress, wait until complete before logging a custom event

Migrated from #25 by @hmedney

Basically this keeps track of the callback in a window.appboy scoped var and provides a new function called _messagingReady(callback). Calls to logCustomEvent() can be wrapped as follows:

this._messagingReady(function() {
  window.appboy.logCustomEvent(eventName, properties);
})

When the messages have been downloaded, the callback is invoked. In testing simple pages, it seems to solve the race condition and make the integration more predictable.

For example, if a page instruments as follows:

analytics.load("{writeKey}");
analytics.identify("{userId}")
analytics.page();

The above change will ensure all the Braze in-app messages have been downloaded before the page custom event is called on the SDK.

[appboy] Pull Request #24: Use messagingReadyCallback in openSession/changeUser

Migrated from #24 by @viparthasarathy

This should ensure that Braze triggers are synced before signaling that we're ready for use.

cc: @froodian @Bucimis

[nielsen-dcr] Fix me! I'm broken!

Migrated from #17 by @CarlosMecha

This is a test issue, please ignore

[amplitude] Pull Request #43: Bump Amplitude SDK version to 4.4.0

Migrated from #43 by @XavierAgostini

This PR bumps the Amplitude SDK to version 4.4.0

Amplitude SDK Changelog: https://github.com/amplitude/Amplitude-JavaScript/blob/master/CHANGELOG.md

[nielsen-dcr] This is the test2

Migrated from #14 by @CarlosMecha

Fix me!

[appboy] Add option to enable error logging

Migrated from #17 by @robinem

We would like to get more info about errors.
Braze SDK has an error logging option, but that is not visible via Segment SDK.
https://www.braze.com/documentation/Web/#error-logging

[nielsen-dcr] New test issue

Migrated from #15 by @CarlosMecha

Fix me! I'm broken!

[rockerbox] Pull Request #5: updates to support xyz.js client-side pixel

Migrated from #5 by @patrickotoole

Porting pull request over from https://github.com/patrickotoole/integration-rockerbox/tree/client_side to this repo

Currently, clients have not been able to use the new features of our pixel. This prevents them from receiving accurate information within the Rockerbox platform. The new implementation will allow them to track all types of events that may occur on their site, giving them greater flexibility.

The former implementation has been deprecated for some time and we are making a renewed push to transition any client to the new implementation.

Current customers integrated with segment should not be impacted by this change.

[livechat] Pull Request #5: Pin karma, karma-mocha dev dependencies

Migrated from #5 by @Peripheral1994

[nielsen-dcr] This is the test2

Migrated from #14 by @CarlosMecha

Fix me!

os

[optimizely] Pull Request #39: Support "Completed Order"

Migrated from #39 by @srthurman

Support the legacy "Completed Order" event name. Some customers still use that, and this change will allow them to use Optimizely as intended without changing their code base.

Error: Connection lost: The server closed the connection.ajs-cli bug

Error: Connection lost: The server closed the connection.

[livechat] Pull Request #6: Bump int-tester to ^3.1.0

Migrated from #6 by @Peripheral1994

[nielsen-dcr] This is the test2

Migrated from #14 by @CarlosMecha

Fix me!