Menu
Menu Sheet Overlay
Search
Search Sheet

Extending a Connector

    Here’s how to extend the connectors that are included in the Mobify Platform. You might want to do this to track analytics events under a different set of credentials for the same analytics service. For example, you may need to track events under multiple Google Analytics properties besides Mobify’s Google Analytics property.

    Table of contents

    Extending the Google Analytics connector #

    Setting up your PWA #

    1. Create a file in web/app/utils/analytics with the following code in it. You’ll want to name the file so that you can identify the connector. For example: ga.js. If you have multiple instances of the connector that you need to extend, you should name the file so that you can identify the instance too. For example: ga-international.js.

       import GoogleAnalytics from 'progressive-web-sdk/dist/analytics/connectors/google-analytics/connector'
      
       let ga
      
       export default class MyGA extends GoogleAnalytics {
           constructor() {
               super('My GA', 'myTrackerName', {
                   ecommerceLibrary: 'ec'          // This should be either 'ec' or 'ecommerce'
               })
           }
      
           ready() {
               ga = window.ga                    // Keeping a reference of the ga object
      
               ga('create', 'UA-########-#', 'auto', {name: this.trackerName})
      
               super.ready(() => {
                   // Any GA specific setup like setting dimension
                   // this.setDimension(1, 'GA custom dimension 1 value')
               })
           }
       }
      

      What is the difference between ec and ecommerce and which one should I use?

      The ecommerce plug-in only allows transaction analytics.

      The ec plug-in is Google Analytics’ Enhanced Ecommerce plug-in. This plug-in enables tracking analytics on user’s shopping experience.

      Which one to use is completely dependent on which mode the client’s Google Analytics is using. Your project manager can request such information from your customer.

    2. Add your newly extended analytics connector to the Analytics Manager

    3. Listen for the built-in events that are tracked by your PWA.

      For each built-in event, the arguments returned should be for the ga function. For example:

           setCurrencyEvent(payload) {
               return ['set', 'currencyCode', payload.currencyCode]
           }
      

      The above will translate to a call to the ga function:

           ga('yourTrackerName.set', 'currencyCode', payload.currencyCode)
      

    Testing Google Analytics #

    When testing or debugging your Google Analytics connector, you should first make use of the Analytics Manager’s built in logging. You can turn this on by following the steps in the Adding a New Connector guide

    The events for your connector will be labeled with the name of your connector. For example, you should see events like My GA sends a pageview event. Using these logs, you should verify 3 things:

    Are all of the expected events being sent?

    Verify that you are seeing all of the events that you expect. For example, if you are tracking the Add to Cart event in your connector, verify that the event is sent when you click on the add to cart button.

    If an event is missing, start by checking your connector. Are the events named correctly?

    Some events, such as pageview and purchase, are automatically instrumented in the Google Analytics connector. As a result, unless you want to override the default behavior of these events, you do not need to include them in your custom Google Analytics connector. If you do override these events, make sure that you call the base Google Analytics connector’s function so that the events are sent and logged properly.

    For example, if you override the pageviewEvent in your custom connector, make sure to call super.pageviewEvent.

    pageviewEvent(payload) {
        // add some custom data to your Google Analytics tracker here
        return super.pageviewEvent(payload)
    }
    

    Are the correct number of events being sent?

    It is important to verify that events are being sent the correct number of times. Duplicated events, especially pageviews, can cause incorrect reporting in Google Analytics. For example, check that only one pageview event is sent for your connector each time the user navigates in the PWA.

    If events are being duplicated, check the code responsible for sending the events. Is it being run too frequently? Also, check your connector and make sure that duplicate events aren’t being sent there.

    Is the data being sent correct?

    The Analytics Manager’s built in logging provides a summary of each event. Verify that the data in this summary is accurate. In particular, check that the GA ID is correct.

    Note that this logging does not include all of the data that is sent with each analytics event. Because of this, we recommend also inspecting the network requests made to Google Analytics to verify that all of the data is correct.

    While previewing the PWA in Chrome, open the Chrome DevTools. Open the Network tab. In the filter, enter collect?. This filter will show only the requests being sent to Google Analytics. Verify that the data sent in the Query String Parameters is correct.

    Note: If your PWA has a service worker installed, you may see duplicate requests in the Network tab. These duplicates will have a gear icon beside them. These requests are handled by the service worker. They are returned from the cache, and don’t actually go out to the network. As a result, you can safely ignore these duplicates. To check that these requests don’t actually reach Google Analytics, you can use a HTTP proxy such as Charles to inspect the traffic. The requests with the gear icon beside them will not appear in Charles log of the traffic.

    Screenshot of Google analytics
requests with and without the gear

    Extending the Google Tag Manager connector #

    Setting up your PWA #

    1. Create a file in web/app/utils/analytics with the following code in it. You’ll want to name the file so that you can identify the connector. For example: gtm.js. If you have multiple instances of the connector that you need to extend, you should name the file so that you can identify the instance too. For example: gtm-international.js.

       import GoogleTagManager from 'progressive-web-sdk/dist/analytics/connectors/google-tag-manager/connector'
      
       export default class MyGTM extends GoogleTagManager {
           constructor() {
               super('My GTM', 'GTM-#######')
           }
       }
      
    2. Add your newly extended analytics connector to the Analytics Manager
    3. Listen for the built-in events that are tracked by your PWA.

      For each built-in event, the arguments returned should be the arguments to the dataLayer.push function. For example:

           pageviewEvent(payload) {
               return {
                   event: 'Pageview',
                   ...payload
               }
           }
      

      The above will translate to a call to the dataLayer.push function:

           window.dataLayer.push({
               event: 'Pageview',
               ...payload
           })
      

    Configuring Google Tag Manager #

    If you need to collect page view related metrics using the Google Analytics tag in a Google Tag Manager container, the following is required so that the collected metrics are as accurate as possible.

    1. Create a custom event trigger for page view

      Note: Do not use the history change trigger type. This trigger type listens for a browser’s history change in order to send a page view event. This leaves no time for other page related metrics, such as page title, to be set before sending a page view event.

    2. Use your custom created trigger to trigger your page view tag

    Debugging Google Tag Manager #

    Pageview events are missing data

    This can happen if the pageview is sent too early, before the page is fully loaded. This can happen if the pageviews are triggered by GTM, instead of by the Analytics Manager. Follow the steps in Configuring Google Tag Manager to set up pageviews that will be triggered by the Analytics Manager.

    If you need to have automatically triggered pageviews, we recommend disabling those pageviews for the PWA and setting up separate, manually triggered pageviews. You can create a flag within the PWA that indicates if the PWA is running or not, such as window.Progressive.isPWA. Disable automatically triggered pageviews when this condition is true.

    Extending the Monetate connector #

    Setting up your PWA #

    1. Create a file in web/app/utils/analytics with the following code in it. You’ll want to name the file so that you can identify the connector. For example: monetate.js. If you have multiple instances of the connector that you need to extend, you should name the file so that you can identify the instance too. For example: monetate-international.

       import Monetate from 'progressive-web-sdk/dist/analytics/connectors/monetate/connector'
      
       export default class MyMonetate extends Monetate {
           constructor() {
               super('My Monetate', 'e.monetate.net/js/2/#############/custom.js')
           }
       }
      

      The customer must supply you with the Monetate asynchronous tag for their account. To find it:

      1. Login to Monetate dashboard
      2. Click on Integration

      3. Click on Tag

      4. Make sure the ASYNCHRONOUS button is showing and copy the highlighted url

    2. Add your newly extended analytics connector to the Analytics Manager

    3. Listen for the built-in events that are tracked by your PWA.

      For each built-in event, we are not expecting any return arguments. However, each function should be interacting with the Monetate API.

           pageviewEvent(payload) {
               this.send(['trackData'])
           }
      

      The above will translate to a call to the monetateQ.push function:

           window.monetateQ.push(['trackData'])
      

    To preview Monetate experiences, follow the Monetate guide

    Extending the Adobe Dynamic Tag Management connector #

    This connecter provides a basic implementation of Adobe Dynamic Tag Management (Adobe DTM) for your PWA. The connector loads Adobe DTM and tracks pageview events. When using project files that were generated with our PWA generator, the connector also tracks the following analytics events:

    If you need to track any other events, you’ll need to do some setup before creating adding custom events.

    Note: If you are using the same code to embed Adobe DTM as your desktop website, some third party scripts that it loads may not be compatible with your PWA because it is a single-page application. We recommend that you review your Adobe DTM configuration so that you don’t encounter any unwanted side effects.

    Setting up your PWA #

    First, create a file in web/app/utils/analytics with the following code in it. You’ll want to name the file so that you can identify the connector. For example: adobe-dtm.js. If you have multiple instances of the connector that you need to extend, you should name the file so that you can identify the instance too. For example: adobe-dtm-international.js.

    import AdobeDynamicTagManager from 'progressive-web-sdk/dist/analytics/connectors/adobe-dynamic-tag-manager/connector'
    
    export default class MyAdobeDynamicTagManager extends AdobeDynamicTagManager {
        constructor() {
            super('My AdobeDynamicTagManager', '$SCRIPT_LOCATION', '$SUITE_ID')
        }
    }
    

    Now we need to replace $SCRIPT_LOCATION and $SUITE_ID in the code above with actual string values.

    Here’s how to get the string value for $SCRIPT_LOCATION:

    1. Log in to the Adobe DTM dashboard. If you don’t have access to the dashboard, you will need to share these instructions with someone who does.
    2. Click on the Embed tab
    3. Expand the Header Code section so that it looks like this:

    4. Copy the value of the src attribute from the <script> tag. If more than one <script> tag is shown, copy from the one that appears under the environment you’re targeting.

    5. Replace $SCRIPT_LOCATION in the index.js file that you created earlier with the string value that you just copied

    Here’s how to get the string value for $SUITE_ID:

    1. Log in to the Adobe DTM dashboard. If you don’t have access to the dashboard, you will need to share these instructions with someone who does.
    2. Go to the Admin section
    3. Go to Dynamic Tag Management
    4. Select the current project. The suite ID will appear under the heading for each environment

    5. Copy the suite ID for the environment that you’re targeting

    6. Replace $SUITE_ID in the index.js file that you created earlier with the string value that you just copied

    Now that you have created a new connector that extends the base Adobe DTM connector, follow this guide to start adding custom events.

    Debugging Adobe Dynamic Tag Management #

    Once you have successfully added the Adobe DTM connector to your project, you can verify its presence by following these instructions and installing Adobe’s DigitalPulse Debugger bookmarklet. Running the debugger will present you with a window similar to the one shown below. Here you can check the variables being set, the version information, and more.