{"id":28159832,"url":"https://github.com/tymate/react-gtm","last_synced_at":"2025-11-11T20:32:54.991Z","repository":{"id":42687346,"uuid":"312443762","full_name":"tymate/react-gtm","owner":"tymate","description":"A Google Tag Manager React library, with sane defaults, augmented with dataLayer management hooks.","archived":false,"fork":false,"pushed_at":"2023-01-06T16:15:35.000Z","size":267,"stargazers_count":1,"open_issues_count":6,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-10T11:05:52.703Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tymate.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-11-13T01:46:56.000Z","updated_at":"2023-05-09T15:37:56.000Z","dependencies_parsed_at":"2023-02-06T06:31:54.354Z","dependency_job_id":null,"html_url":"https://github.com/tymate/react-gtm","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tymate%2Freact-gtm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tymate%2Freact-gtm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tymate%2Freact-gtm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tymate%2Freact-gtm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tymate","download_url":"https://codeload.github.com/tymate/react-gtm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254319704,"owners_count":22051075,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-15T10:11:46.207Z","updated_at":"2025-11-11T20:32:54.922Z","avatar_url":"https://github.com/tymate.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# React GTM\n\nA Google Tag Manager React library, with sane defaults, augmented with `dataLayer` management hooks.\n\nThis library supports :\n- Sending `virtual-pageview` events on initial load and each route change.\n- Providing `dataLayer` values via a `useDataLayer` hook.\n- Pushing custom events to the `dataLayer`.\n- Providing a `dataLayer` builder function, which is used to augment the `virtual-pageview` event before it's pushed.\n- Multiple Tag Manager containers loading.\n\n\n## Installation\n\nUsing yarn :\n```\nyarn add @tymate/react-gtm\n```\n\n### Dependencies\n\nThe package uses `react-helmet` to insert `\u003cscript /\u003e` tags in the page's `head`.\nYou should check it's presence in your project's dependencies, and just to be sure, run\n\n```\nyarn add react-helmet\n```\n\n## A Google Tag Manager primer\n\n### Tags\nGoogle Tag Manager provides an interface to define multiple ***tags*** in a web interface.\n\nThese tags are used to dispatch analytics to Google Analytics and other audience and conversions reporting tools. Predefined tags are available for common services, GTM also supports custom Javascript snippets to be used as tags. Each service can be used on multiple tags, in order to pass different parameters and report different types of events.\n\n### Triggers\n\nTags are called by ***triggers*** which are also defined in Tag Manager's interface. Triggers can be defined by non-developers, with a WYSIWIG tool that can help people associating a button, a timeout or anything else with a tag to be called.\n\nTags defined in this way can tend to be messy, since it uses DOM elements classes or IDs which can be subject to change between releases.\n\nIt's hopefully possible to define ***custom events*** which can be called in the website's code by leveraging the ***dataLayer***.\n\n### Variables\n\nVariables are a way to integrate data coming from the website in the ***tags***, who will in turn send them to the underlying services.\n\nTag Manager's UI offers some common variables to be inserted in the tags (page location, referrer...) and allows them to be augmented with variables coming from the `dataLayer`.\n\n### Container\n\nA container is the combination of tags, triggers and variables, and is represented by a container ID in the form of `GTM-XXX`.\n\nEach container has a `\u003cscript /\u003e` tag to be embedded in the target website, which will trigger GTM logic.\n\n### DataLayer\n\n`window.dataLayer` is a global variable that each container watches. It's basically an array of objects containing all variables and events pushed to it, in the following format :\n\n```js\n{\n  \"event\": \"myEvent\",\n  \"var1\": \"A variable\",\n  \"var2\": \"Another one\"\n  // Whenever Wherever Whatever\n  // (a song by Maxwell)\n  // (i still prefer it's \"Embrya\" album)\n}\n```\n\n## Reference\n\n### `\u003cGtmProvider /\u003e`\n\n`\u003cGtmProvider /\u003e` is the component responsible for including container tags in the DOM,  sending the `vitual-pageview` events on location change and populating the dataLayer with data passed in children component's hooks.\n\nIt takes the following properties :\n- `location` takes your current page's location as value.\n\n  It's mandatory to pass it to the component, and allows it to be agnostic of whatever routing library you are using.\n\n- `data` is an arbitrary property passed as first argument to your `useDataLayerBuilder()` callbacks.\n\n  It allows the children components to compute some derived dataLayer entry that can be retrieved from the parent `\u003cGtmProvider /\u003e`, which allows to ensure variables are set on\n  the `virtual-pageview` event calls.\n\n  Its most useful case is in Gatsby, where you can use it to pass your page's `data`, fetched from the GraphQL store.\n\n- `gtmTags` is a list of Tag Manager Container Ids to be enabled.\n\n- `initialDataLayer` is an object of variables which will always be merged to the `virtual-pageview` events.\n\n- `isInitialDataLayerReady`, defaults to `true`, if passed `false`, prevents the sending of pageView events before becoming `true`.\n\n- `hasDebugEnabled` is a boolean enabling the logging of all the dataLayer pushes the library makes.\n\n```es6\nimport { GTMProvider } from '@tymate/react-gtm';\nimport { useLocation } from \"@reach/router\"\n\nconst location = useLocation();\n\n\u003cGTMProvider\n  hasDebugEnabled\n  data={{\n    artist: {\n      name: 'Kedr Livanskiy',\n      tracks: [\n        { name: 'Разрушительный круг' }\n      ]\n    }\n  }}\n  location={location}\n  gtmTags={['GTM-XXX']}\n  initialDataLayer={{\n    language,\n    isAuthenticated,\n    customVendors,\n  }}\n\u003e\n  \u003cMyComponent /\u003e\n\u003c/GTMProvider\u003e\n```\n\n### `useDataLayerBuilder()`\n\n`useDataLayerBuilder()` is a hook taking a `(data) =\u003e {}` function as argument, which should return an object of variables to be included in the `virtual-pageview` events.\n\nThe function you define as argument will be passed with the `data` provided to `\u003cGTMProvider /\u003e` and called on route change.\n\nThis is the main method to use for setting variables on pages, since it's mostly ensured to be called before the `virtual-pageview` is sent.\n\n```es6\nimport { useDataLayerBuilder } from '@tymate/react-gtm';\n\nuseDataLayerBuilder(({ hotel }) =\u003e ({\n  pageType: 'hotel',\n  searchHotel: hotel.displayName,\n  searchHotelId: hotel.originalId,\n  hotelStars: hotel?.stars,\n}));\n```\n\n### `useGTM()`\n\n`useGTM()` is a hook that returns public properties of the underlying context used by the library.\n\n- `pushDataLayer` is a method pushing what it takes as argument into the underlying tagManager `dataLayer`.\n \n  It's the equivalent of doing a `window.dataLayer.push(data)` call, and mainly serves as a way to send events to the Google Tag Manager container.\n\n  [Examples from Google's documentation](https://developers.google.com/tag-manager/devguide) can be integrated to your project via this method.\n\n  \u003e ⚠️ Use this only to push events and their associated data in the dataLayer.\n  \u003e\n  \u003e Pushing data to the `dataLayer` without an `event` key will delay the sending of the variables until the next event sent.\n\n```es6\nimport { useGTM } from '@tymate/react-gtm';\n\nconst { pushDataLayer } = useGTM();\n\npushDataLayer({\n  event: 'checkout',\n  ecommerce: {\n    checkout: {\n      actionField: {\n        step: 1,\n      },\n    },\n  },\n});\n```\n\n### `useDataLayer()`\n`useDataLayer()` is a hook which takes an object to be pushed in the `dataLayer`.\n\nYou should only pass it dataLayer variables, and use the `pushDataLayer` returned by `useGTM()` instead to push events.\n\nBehind the scene, it makes a call to `pushDataLayer` each time the object passed as parameter changes.\n\n```es6\nuseDataLayer({\n  ecommerce: {\n    detail: {\n      actionField: { list: 'Search' },\n      products: [\n        {\n          id: hotel.originalId,\n          name: hotel.displayName,\n          brand: 'Feelingo',\n          category: 'Hotel',\n        },\n      ],\n    },\n  },\n});\n```\n\n\u003e ⚠️🚨 ❗️ **Achtung**\n\u003e\n\u003e The main use case of this hook is to define variables to be sent to Tag Manager on the next dataLayer push containing an `event` key.\n\u003e\n\u003e It can come in handy in some situations, but each object pushed to the dataLayer should generally have an `event` key.\n\n## Integrating with Gatsby\n\nOn Gatsby websites, you can integrate `react-gtm` by first placing the `\u003cGTMProvider /\u003e` component in the `gatsby-browser.js` `wrapPageElement` method :\n\n```es6\nimport { GTMProvider } from '@tymate/react-gtm';\n\nexport const wrapPageElement = ({\n  element,\n  props: { data, location },\n}) =\u003e {\n  return (\n    \u003c\u003e\n      \u003cGTMProvider\n        data={data}\n        location={location}\n        gtmTags={['GTM-XXX']}\n      \u003e\n        {element}\n      \u003c/GTMProvider\u003e\n    \u003c/\u003e\n  )\n};\n```\n\nThen use the provided hooks in your pages and templates.\n\n## References\n\nThere's some good amount of litterature on Google, third-party, and dubious SEO sites on Google Tag Manager integrations. It's worth checking out :\n\n- [Google Tag Manager Developer Guide](https://developers.google.com/tag-manager/devguide) (especially the Flash/ActionScipt part !)\n- [Google's Enhanced Ecommerce](https://developers.google.com/tag-manager/enhanced-ecommerce), if you have to integrate Google Analytics conversions and funnel analytics.\n- [Santiano Tag Manager Containers](https://santiano.io/google-tag-manager-containers), a collection of premade tags/variables/triggers to be imported in Tag Manager, and the accompanying documentation explaining how you should integrate their events in your dataLayer. The marketing agency in charge of the website is probably already using it !\n\n## Tooling\n- [Google Tag Assistant](https://tagassistant.google.com/) enables you to see exactly how Tag Manager interprets your dataLayer pushes and which tags are called in reaction.\n- [Google Analytics Debugger](https://chrome.google.com/webstore/detail/google-analytics-debugger/jnkmfdileelhofjcijamephohjechhna) which allows you to see the end-of-chain Google Analytics and `gtag.js` calls.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftymate%2Freact-gtm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftymate%2Freact-gtm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftymate%2Freact-gtm/lists"}