How to Integrate Rudderstack with a Gatsby Website
Step-by-step guide to integrate RudderStack with your Gatsby site for event tracking.
Last updated
Was this helpful?
Step-by-step guide to integrate RudderStack with your Gatsby site for event tracking.
Last updated
Was this helpful?
You can quickly and easily get Rudderstack up and running in your Gatsby application by using Rudderstack's Gatsby plugin. It makes it easy to integrate your Gatsby website with the Rudderstack API and easily track events.
Use multiple write keys (one for production environment, another optional one for development)
Disable page view tracking (just in case you want to add it later manually)
Always up-to-date and maintained by the RudderStack team
To install the plugin, run the following command with the package manager of your choice:
NPM: $ npm install --save gatsby-plugin-rudderstack
YARN: $ yarn add gatsby-plugin-rudderstack
In your gatsby-config.js
file you first need to add your write key from your account. You can find this in your RudderStack dashboard.
identify()
method:The identify()
method allows you to link users and their actions to a specific user ID.
A sample example of how the identify()
method works in Gatsby is as shown:
In the above example, information such as the user ID, email along with contextual information such as IP address, anonymousId
, etc. will be captured.
There is no need to call identify()
for anonymous visitors to your website. Such visitors are automatically assigned an anonymousId
.
track()
methodThe track()
method allows you to track any actions that your users might perform. A sample example of how the track()
method works is as shown:
In the above example, the method tracks the event ‘test track event GA3’, and information such as the revenue, currency, and anonymousId. You can use this method to track various other success metrics for your website, such as user signups, item purchases, article bookmarks, and much more.
To override contextual information, for ex: anonymizing IP and other contextual fields like page
properties, the following template can be used. Similarly, you can override the auto-generated anonymousId
with the provided ID. For this, follow the snippet below:
If you want to track pageviews automatically, set trackPage
to true
in your gatsby-config.js
file. What we mean by automatically is that whenever there is a route change, RudderStack leverages Gatsby's onRouteUpdate
API in the gatsby-browser.js
file (link) to invoke window.rudderanalytics.page()
on each route change.
However, if you want to pass in properties along with the pageview call (it is common to see some users pass in some user or account data with each page
call), then you'll have to set trackPage: false
and call it yourself in your gatsby-browser.js
file, as shown below:
You’ve now successfully installed rudder-analytics.js
tracking. You can enable and use any event destination to send your event data via RudderStack.
There are cases when you may want to tap into the features provided by end destination SDKs to enhance tracking and other functionalities.
RudderStack's JavaScript SDK exposes a ready
API with a callback
parameter, that fires when the SDK is done initializing itself and other third-party native SDK destinations. For example:
For detailed technical documentation and troubleshooting guide on the RudderStack’s JavaScript SDK, refer to JavaScript documentation.
RudderStack's Querystring API allows you to trigger track
, identify
calls using query parameters.
If you pass the following parameters in the URL, then it will trigger the corresponding SDK API call. For example:
For the above URL, the below SDK calls will be triggered:
You may use the below parameters as a querystring parameter and trigger the corresponding call:
Parameter
Description
ajs_uid
Makes a rudderanalytics.identify()
call with userId
having the value of the parameter value.
ajs_aid
Makes a rudderanalytics.setAnonymousId()
call with anonymousId
having the value of the parameter value.
ajs_event
Makes a rudderanalytics.track()
call with event
name as parameter value.
ajs_prop_<property>
If ajs_event
is passed as querystring, value of this parameter will populate the properties of the corresponding event in the track
call.
ajs_trait_<trait>
If ajs_uid
is provided as querystring, value of this parameter will populate the traits of the identify
call made.
You can also define callbacks to the common methods of the rudderanalytics
object.
Currently, the functionality is supported for syncPixel
method which is called in the SDK when making sync calls in integrations for relevant destinations. For example, you can load rudderanalytics
with callbacks in your Gatsby browser file as shown below:
In order for this to work well, you must also set the manualLoad
option to true
in your Gatsby configuration, and load RudderStack in the browser's Gatsby file manually.
In the above example, we defined a syncPixelCallback
on the rudderanalytics
object before the call to load the SDK. This will lead to calling of this registered callback with the parameter {destination: <destination_name>}
whenever a sync call is made from the SDK for relevant integrations like Lotame.
The callback can be supplied in options parameter like below as well:
This plugin is released under the AGPLv3 License.
For more information on any of the sections in this guide, please feel free to contact us. You can also start a conversation in our Slack community, or even see RudderStack in action.