gatsby-plugin-rudderstack 1.0.4 → 1.1.1

package/README.md

@@ -3,21 +3,21 @@
 <p align="center"><b>The warehouse-first customer data platform built for devs.</b></p>
 <br/>
 
-# The Rudderstack Plugin for Gatsby.
+# The RudderStack Plugin for Gatsby.
 
-This is a way for you to quickly and easily get Rudderstack up and running in your Gatsby application.
+This is a way for you to quickly and easily get RudderStack up and running in your Gatsby application.
 
 Questions? Please join our [Slack channel](https://resources.rudderstack.com/join-rudderstack-slack) or read about us on [Product Hunt](https://www.producthunt.com/posts/rudderstack).
 
 # Why Use This plugin
 
-This plugin makes it easy to integrate your Gatsby website with the Rudderstack API and easily track events.
+This plugin makes it easy to integrate your Gatsby website with the RudderStack API and easily track events.
 
 # Key Features
 
 - use multiple write keys (one for prod env, another optional one for dev)
 - disable page view tracking (just in case you want to add it later manually)
-- up to date (Rudderstack team maintained)
+- up to date (RudderStack team maintained)
 
 ## Install
 
@@ -58,24 +58,23 @@ plugins: [
 
       // If you need to proxy events through a custom data plane,
       // add a `dataPlaneUrl` property (defaults to https://hosted.rudderlabs.com )
-      // Rudderstack docs:
+      // RudderStack docs:
       //   - https://docs.rudderstack.com/rudderstack-sdk-integration-guides/rudderstack-javascript-sdk#3-1-load
       dataPlaneUrl: `https://override-rudderstack-endpoint`,
 
       // Add a `controlPlaneUrl` property if you are self-hosting the Control Plane
-      // Rudderstack docs:
+      // RudderStack docs:
       //   - https://docs.rudderstack.com/rudderstack-sdk-integration-guides/rudderstack-javascript-sdk#3-1-1-self-hosted-control-plane
       controlPlaneUrl: `https://override-control-plane-url`,
 
-      // boolean (defaults to false); whether to delay load Rudderstack
+      // boolean (defaults to false); whether to delay load RudderStack
       // ADVANCED FEATURE: only use if you leverage client-side routing (ie, Gatsby <Link>)
-      // This feature will force Rudderstack to load _after_ either a page routing change
-      // or user scroll, whichever comes first. This delay time is controlled by
-      // `delayLoadTime` setting. This feature is used to help improve your website's
+      // This feature will force RudderStack to load _after_ either a page routing change
+      // or user scroll, or after `delayLoadTime` elapses, whichever comes first. This feature is used to help improve your website's
       // TTI (for SEO, UX, etc).  See links below for more info.
       // NOTE: But if you are using server-side routing and enable this feature,
-      // Rudderstack will never load (because although client-side routing does not do
-      // a full page refresh, server-side routing does, thereby preventing Rudderstack
+      // RudderStack will never load (because although client-side routing does not do
+      // a full page refresh, server-side routing does, thereby preventing RudderStack
       // from ever loading).
       // See here for more context:
       // GIF: https://github.com/benjaminhoffman/gatsby-plugin-segment/pull/19#issuecomment-559569483
@@ -83,9 +82,10 @@ plugins: [
       // Problem/solution: https://marketingexamples.com/seo/performance
       delayLoad: false,
 
-      // number (default to 1000); time to wait after scroll or route change
+      // number (default to 1000); time to wait after the page loads
+      // to load the RudderStack SDK
       // To be used when `delayLoad` is set to `true`
-      delayLoadTime: 1000
+      delayLoadTime: 1000,
 
       // Whether to completely skip calling `analytics.load()`.
       // ADVANCED FEATURE: only use if you are calling `analytics.load()` manually
@@ -93,13 +93,19 @@ plugins: [
       // that will call it for you.
       // Useful for only loading the tracking script once a user has opted in to being tracked, for example.
       // *Another use case is if you want to add callbacks to the methods at load time.
-      manualLoad: false
+      manualLoad: false,
 
       // string ('async' or 'defer'); whether to load the RudderStack SDK async or defer. Anything else
       // will load normally.
       // 'async' will load the SDK as <script async></script>
       // 'defer' will load the SDK as <script defer></script>
-      loadType: 'default'
+      loadType: 'default',
+
+      // Options to the `load` API
+      // Note: The above `controlPlaneUrl` overrides the `configUrl` field in this object
+      loadOptions: {
+        ...
+      }
     }
   }
 ];
@@ -191,6 +197,8 @@ exports.onRouteUpdate = () => {
 };
 ```
 
+Note: The above code snippet might not give the best results all the time as it doesn't take various SDK loading scenarios into consideration. Hence, if you are not tracking page views automatically, then clone the contents of the `gatsby-browser.js` from the package and make necessary modifications.
+
 You’ve now successfully installed `rudder-analytics.js` tracking. You can enable and use any event destination to send your event data via RudderStack, in no time at all!
 
 ## [](https://github.com/rudderlabs/rudder-sdk-js/blob/master/README.md#step-4-check-ready-state)Step 4: Check Ready State

package/gatsby-browser.js

@@ -6,22 +6,48 @@ exports.onRouteUpdate = function (_ref, _ref2) {
       _ref2$trackPageDelay = _ref2.trackPageDelay,
       trackPageDelay = _ref2$trackPageDelay === undefined ? 50 : _ref2$trackPageDelay;
 
-  function trackRudderstackPage() {
-    var delay = Math.max(0, trackPageDelay);
+  function trackRudderStackPage() {
+    if (trackPage) {
+      // Adding a delay (defaults to 50ms when not provided by plugin option `trackPageDelay`)
+      // ensure that the RudderStack route tracking is in sync with the actual Gatsby route
+      // (otherwise you can end up in a state where the RudderStack page tracking reports
+      // the previous page on route change).
+      var delay = Math.max(0, trackPageDelay);
 
-    window.setTimeout(function () {
-      if (trackPage) {
+      window.setTimeout(function () {
         window.rudderanalytics && window.rudderanalytics.page(document.title);
-      }
-    }, delay);
+      }, delay);
+    }
   }
 
-  // Track only non-home page views
-  if (prevLocation) {
-    if (window.rudderSnippetLoaded === false && window.rudderSnippetLoading === false) {
-      window.rudderSnippetLoader();
+  // IMPORTANT: If you are cloning the contents of this file,
+  // we recommend to keep this section of the code intact and 
+  // just change the tracking logic in `trackRudderStackPage` method.
+  if (window.rudderSnippetLoaded === false) {
+    if (window.rudderSnippetLoading === true) {
+      // As the loading is in progress, set the alternate callback function
+      // to track page
+      window.rudderSnippetLoadedCallback = function () {
+        trackRudderStackPage();
+      };
     } else {
-      trackRudderstackPage();
+      // if it is not the first page
+      if (prevLocation) {
+        // Trigger the script loader and set the callback function
+        // to track page
+        window.rudderSnippetLoadedCallback = undefined;
+        window.rudderSnippetLoader(function () {
+          trackRudderStackPage();
+        });
+    } else {
+        // As this is the first page, set the alternate callback function
+        // to track page and wait for the scroll event to occur (for SDK to get loaded)
+        window.rudderSnippetLoadedCallback = function () {
+          trackRudderStackPage();
+        }
+      }
     }
+  } else {
+    trackRudderStackPage();
   }
 };

package/gatsby-ssr.js

@@ -4,65 +4,129 @@ var _react = require("react");
 
 var _react2 = _interopRequireDefault(_react);
 
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+function _interopRequireDefault(obj) {
+  return obj && obj.__esModule ? obj : { default: obj };
+}
 
 exports.onRenderBody = function (_ref, pluginOptions) {
   var setHeadComponents = _ref.setHeadComponents;
   var trackPage = pluginOptions.trackPage,
-      prodKey = pluginOptions.prodKey,
-      devKey = pluginOptions.devKey,
-      _pluginOptions$dataPl = pluginOptions.dataPlaneUrl,
-      dataPlaneUrl = _pluginOptions$dataPl === undefined ? "https://hosted.rudderlabs.com" : _pluginOptions$dataPl,
-      controlPlaneUrl = pluginOptions.controlPlaneUrl,
-      delayLoad = pluginOptions.delayLoad,
-      delayLoadTime = pluginOptions.delayLoadTime,
-      manualLoad = pluginOptions.manualLoad,
-      loadType = pluginOptions.loadType,
-      useNewSDK = pluginOptions.useNewSDK;
-
+    prodKey = pluginOptions.prodKey,
+    devKey = pluginOptions.devKey,
+    _pluginOptions$dataPl = pluginOptions.dataPlaneUrl,
+    dataPlaneUrl =
+      _pluginOptions$dataPl === undefined
+        ? "https://hosted.rudderlabs.com"
+        : _pluginOptions$dataPl,
+    controlPlaneUrl = pluginOptions.controlPlaneUrl,
+    delayLoad = pluginOptions.delayLoad,
+    delayLoadTime = pluginOptions.delayLoadTime,
+    manualLoad = pluginOptions.manualLoad,
+    loadType = pluginOptions.loadType,
+    useNewSDK = pluginOptions.useNewSDK,
+    loadOptions = pluginOptions.loadOptions,
+    sdkURL = pluginOptions.sdkURL;
 
   var sdkSrc = "https://cdn.rudderlabs.com/v1/rudder-analytics.min.js";
-  if (useNewSDK) {
+  if (sdkURL) sdkSrc = sdkURL;
+  else if (useNewSDK) {
     sdkSrc = "https://cdn.rudderlabs.com/v1.1/rudder-analytics.min.js";
   }
 
-  if (!prodKey || prodKey.length < 10) console.error("Your Rudderstack prodKey must be at least 10 char in length.");
+  if (!prodKey || prodKey.length < 10)
+    console.error(
+      "Your RudderStack prodKey must be at least 10 char in length."
+    );
 
-  if (devKey && devKey.length < 10) console.error("If present, your Rudderstack devKey must be at least 10 char in length.");
+  if (devKey && devKey.length < 10)
+    console.error(
+      "If present, your RudderStack devKey must be at least 10 char in length."
+    );
 
   var writeKey = process.env.NODE_ENV === "production" ? prodKey : devKey;
 
-  var loadConfig = controlPlaneUrl ? "'" + writeKey + "', '" + dataPlaneUrl + "', {configUrl: '" + controlPlaneUrl + "'}" : "'" + writeKey + "', '" + dataPlaneUrl + "'";
-
-
-  var snippet = "rudderanalytics=window.rudderanalytics=[];for(var methods=[\"load\",\"page\",\"track\",\"identify\",\"alias\",\"group\",\"ready\",\"reset\",\"getAnonymousId\",\"setAnonymousId\"],i=0;i<methods.length;i++){var method=methods[i];rudderanalytics[method]=function(a){return function(){rudderanalytics.push([a].concat(Array.prototype.slice.call(arguments)))}}(method)}\n  " + (delayLoad || manualLoad ? "" : "rudderanalytics.load(" + loadConfig + ")") + ";\n";
+  var loadConfig = "'" + writeKey + "', '" + dataPlaneUrl + "'";
 
-  var delayedLoader = "\n      window.rudderSnippetLoaded = false;\n      window.rudderSnippetLoading = false;\n      window.rudderSnippetLoader = function (callback) {\n        if (!window.rudderSnippetLoaded && !window.rudderSnippetLoading) {\n          window.rudderSnippetLoading = true;\n          function loader() {\n            window.rudderanalytics.load(" + loadConfig + ");\n            window.rudderSnippetLoading = false;\n            window.rudderSnippetLoaded = true;\n            window.rudderanalytics.page(document.title);\n            if(callback) {callback()}\n          };\n          setTimeout(\n            function () {\n              \"requestIdleCallback\" in window\n                ? requestIdleCallback(function () {loader()})\n                : loader();\n            },\n            " + delayLoadTime + " || 1000\n          );\n        }\n      }\n      window.addEventListener('scroll',function () {window.rudderSnippetLoader()}, { once: true });\n    ";
+  if (loadOptions) {
+    // Override config URL if provided separately
+    loadOptions.configUrl = controlPlaneUrl || loadOptions.configUrl;
+    loadConfig += ", " + JSON.stringify(loadOptions);
+  }
 
-  var snippetToUse = "\n      " + (delayLoad && !manualLoad ? delayedLoader : "") + "\n      " + snippet + "\n    ";
+  var snippet =
+    'rudderanalytics=window.rudderanalytics=[];for(var methods=["load","page","track","identify","alias","group","ready","reset","getAnonymousId","setAnonymousId"],i=0;i<methods.length;i++){var method=methods[i];rudderanalytics[method]=function(a){return function(){rudderanalytics.push([a].concat(Array.prototype.slice.call(arguments)))}}(method)}\n  ' +
+    (delayLoad || manualLoad
+      ? ""
+      : "rudderanalytics.load(" + loadConfig + ")") +
+    ";\n";
+
+  const delayedLoader = `
+      window.rudderSnippetLoaded = false;
+      window.rudderSnippetLoading = false;
+      window.rudderSnippetLoadedCallback = undefined;
+      window.rudderSnippetLoader = function (callback) {
+        if (!window.rudderSnippetLoaded && !window.rudderSnippetLoading) {
+          window.rudderSnippetLoading = true;
+          function loader() {
+            window.rudderanalytics.load(${loadConfig});
+            window.rudderSnippetLoading = false;
+            window.rudderSnippetLoaded = true;
+            if (callback) { callback(); }
+            if (window.rudderSnippetLoadedCallback) {
+              window.rudderSnippetLoadedCallback();
+              window.rudderSnippetLoadedCallback = undefined;
+            }
+          };
+
+          "requestIdleCallback" in window
+            ? requestIdleCallback(function () { loader(); })
+            : loader();
+        }
+      }
+      window.addEventListener('scroll',function () {window.rudderSnippetLoader()}, { once: true });
+      setTimeout(
+        function () {
+          "requestIdleCallback" in window
+            ? requestIdleCallback(function () { window.rudderSnippetLoader(); })
+            : window.rudderSnippetLoader();
+        },
+        ${delayLoadTime} || 1000
+      );
+    `;
+
+  var snippetToUse =
+    "\n      " +
+    (delayLoad && !manualLoad ? delayedLoader : "") +
+    "\n      " +
+    snippet +
+    "\n    ";
 
   if (writeKey) {
-    var tags = [_react2.default.createElement("script", {
-      key: "plugin-rudderstack",
-      dangerouslySetInnerHTML: { __html: snippetToUse }
-    })];
+    var tags = [
+      _react2.default.createElement("script", {
+        key: "plugin-rudderstack",
+        dangerouslySetInnerHTML: { __html: snippetToUse },
+      }),
+    ];
 
     var tag = void 0;
 
-    if (loadType == 'async') {
-      tag = _react2.default.createElement("script", { async: true,
+    if (loadType == "async") {
+      tag = _react2.default.createElement("script", {
+        async: true,
         key: "rudderstack-cdn",
-        src: sdkSrc
+        src: sdkSrc,
       });
-    } else if (loadType == 'defer') {
-      tag = _react2.default.createElement("script", { defer: true,
+    } else if (loadType == "defer") {
+      tag = _react2.default.createElement("script", {
+        defer: true,
         key: "rudderstack-cdn",
-        src: sdkSrc
+        src: sdkSrc,
       });
     } else {
       tag = _react2.default.createElement("script", {
         key: "rudderstack-cdn",
-        src: sdkSrc
+        src: sdkSrc,
       });
     }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gatsby-plugin-rudderstack",
-  "version": "1.0.4",
-  "description": "Event tracking with Rudderstack in your Gatsby frontend.",
+  "version": "1.1.1",
+  "description": "Event tracking with RudderStack in your Gatsby frontend.",
   "main": "gatsby-ssr.js",
   "scripts": {
     "build": "babel src --out-dir . --ignore __tests__",
@@ -18,7 +18,7 @@
     "gatsby",
     "gatsby-plugin"
   ],
-  "author": "Rudderstack",
+  "author": "RudderStack",
   "license": "AGPL-3.0-only",
   "bugs": {
     "url": "https://github.com/rudderlabs/gatsby-plugin-rudderstack/issues"