{"id":19948,"date":"2020-04-17T09:06:45","date_gmt":"2020-04-17T09:06:45","guid":{"rendered":"http:\/\/refiner.io\/documentation\/?post_type=knowledgebase&p=19948"},"modified":"2026-04-08T16:22:29","modified_gmt":"2026-04-08T16:22:29","slug":"google-tag-manager","status":"publish","type":"knowledgebase","link":"https:\/\/refiner.io\/docs\/kb\/install-client\/google-tag-manager\/","title":{"rendered":"Install with Google Tag Manager"},"content":{"rendered":"\n\n\n

Introduction<\/h2>\n\n\n\n

Google Tag <\/a>Manager<\/a> (GTM) is a free tool that allows you to easily add or remove JavaScript tags to your web application without requiring any code changes. Users of GTM can install the Refiner client needed to launch surveys with a few clicks only.<\/p>\n\n\n\n

Install Refiner GTM tag<\/h2>\n\n\n\n

To install the JavaScript SDK with Google Tag Manager, please follow these steps:<\/p>\n\n\n\n

    \n
  1. Navigate to the “Tags” section in your Google Tag Manager container <\/li>\n\n\n\n
  2. Click on “Add New Tag”<\/li>\n\n\n\n
  3. Name your new tag “Refiner” and click “Choose a tag …”<\/li>\n\n\n\n
  4. Navigate to the “Community Tags” by clicking on the banner above the tag list<\/li>\n\n\n\n
  5. Scroll to “Refiner” and click “Add to Workspace”<\/li>\n\n\n\n
  6. Fill in the “Project ID”. You can find your project ID on the Installation page inside your Refiner account.<\/li>\n\n\n\n
  7. Set the trigger for the Refiner snippet to “All Pages – Page View” <\/li>\n\n\n\n
  8. Publish your updated Workspace<\/li>\n<\/ol>\n\n\n\n

    That’s it! The Refiner client is now installed and ready to launch surveys on your website.<\/p>\n\n\n

    \n
    \"\"<\/figure><\/div>\n\n\n

    Identify users<\/h2>\n\n\n\n

    If you want to launch surveys for logged-in users of your web-app using GTM, further installation steps are needed. Whenever possible, we recommend to identify your users as it unlocks many features of Refiner, such as user segmentation and more data integrations as described here<\/a>.<\/p>\n\n\n\n

    Create variables for your user data<\/h3>\n\n\n\n

    As a first step, make sure that all user data fields which you want to send to Refiner are available as variables. <\/p>\n\n\n\n

    Go to “Variables” in your GTM account and check if you already have “User-Defined Variables<\/a>“. If you don’t, go ahead and create one for each data field you want to sync to Refiner. <\/p>\n\n\n\n

    At a minimum, you need to create a variable for the identifier (e.g. userId) you’ll use to identify users. You can choose to create other variables if you want to sync more data to your Refiner account.<\/p>\n\n\n

    \n
    \"\"<\/figure><\/div>\n\n\n

    Map user data from to Refiner tag<\/h3>\n\n\n\n

    Once user data was defined with variables, it’s time to map them in the Refiner tag setup. <\/p>\n\n\n\n

    Go to the Refiner tag configuration panel and map the User ID or Email as shown below. You can also provide the user name. <\/p>\n\n\n\n

    You can send additional user traits from your User-Defined Variables to Refiner. All traits sent to Refiner can be used to segment your users and create target audiences<\/a>.<\/p>\n\n\n

    \n
    \"\"<\/figure><\/div>\n\n\n

    Provide an Identity Verification Token (optional)<\/h3>\n\n\n\n

    If you are using the optional Identify Verification<\/a> security feature, you can provide the computed signature as a user trait using “identify_verification_signature<\/em>” for the field identifier.<\/p>\n\n\n\n

    Please make sure to always compute the signature on the backend and never client-side in the frontend code.<\/p>\n\n\n\n

    You can verify that your Refiner installation works correctly by opening the Developer Console of your web browser. If you see requests to our server failing with a 403 code, your signature is not calculated correctly.<\/p>\n\n\n\n

    Attach data to responses<\/h2>\n\n\n\n

    Our GTM tag allows you to attach any kind of contextual data to survey responses of your users. This data can be either static text, dynamic data coming from the Data Layer, or Magic Variables<\/a>.<\/p>\n\n\n\n

    This option works independently from identifying your users. You can provide contextual data when surveying anonymous or logged-in users.<\/p>\n\n\n

    \n
    \"\"<\/figure><\/div>\n\n\n

    Track user events<\/h2>\n\n\n\n

    To track a user event<\/a> in Refiner with GTM you can create a Custom HTML Tag<\/a> element which executes the following JavaScript code:<\/p>\n\n\n\n

    <script>\n_refiner('trackEvent', 'Your Event Name');\n<\/script><\/pre>\n\n\n\n
    Once you created this tag, you can call it in your GTM setup whenever you want to track the event.<\/p>\n\n\n\n
    Please note that tracking events is only available for logged-in users that you identified with a User ID (see above).<\/p>\n\n\n\n
    Troubleshoot GTM installation<\/h2>\n\n\n\n
    If your Refiner surveys are not launching as expected, we recommend to troubleshoot your GTM installation by following the steps below.<\/p>\n\n\n\n
    Check if the Refiner tag is loaded<\/h3>\n\n\n\n
    Method #1: Try launching Debug Mode<\/h4>\n\n\n\n
    Our JavaScript SDK has a built-in Debug Mode<\/a> which can provide useful information on the current state of the client.<\/p>\n\n\n\n
    You can enable the Debug Mode by executing some code in the browser console or with a URL parameter. Both methods are described here<\/a>.<\/p>\n\n\n\n
    If our JavaScript client was loaded correctly, you should see a debug window telling you if a connection to our servers was established and which environment ID was set.<\/p>\n\n\n
    \n
    \"\"<\/figure><\/div>\n\n\n
    The debug window also tells you whether the client is currently operating in “Identified User” or “Anonymous User” mode. <\/p>\n\n\n\n
    Method #2: Check the HTML document<\/h4>\n\n\n\n
    If the Debug Mode described above is not showing any information, the Refiner client is probably not loaded correctly to your HTML document. <\/p>\n\n\n\n
    Open the developer console of your browser and navigate to the “Elements” tab. If you search for “refiner”, our JavaScript tag should show up as shown below.<\/p>\n\n\n
    \n
    \"\"<\/figure><\/div>\n\n\n
    If the JavaScript tag does not show up, it means that the Refiner tag was not loaded by Google Tag Manager.<\/p>\n\n\n\n
    To resolve this issue, go to your GTM account and check that you published your latest changes and that the trigger event for our tag is set correctly.<\/p>\n\n\n\n
    Method #3: Inspect network tab<\/h4>\n\n\n\n
    You can inspect the network tab of the developer console to check if the Refiner client was loaded.<\/p>\n\n\n\n
    Open the Developer Console of your browser and navigate to “Network”.<\/p>\n\n\n\n
    Setting the filters of the request filter to “Fetch\/XHR” and searching for “refiner” shows all communication between your browser and our backend servers. <\/p>\n\n\n\n
    If you see requests to the api.refiner.io<\/em>, it means that our client was loaded successfully.<\/p>\n\n\n\n
    Clicking on a request gives you access to the Payload (screenshot below) and the Response of our servers.<\/p>\n\n\n
    \n
    \"\"<\/figure><\/div>\n\n\n
    If you are identifying your users, the Payload of each request should have a value either for contact_remote_id<\/em> or contact_email<\/em>.<\/p>\n\n\n\n
    All requests should end with a 200 or 201 status response code. If any of the requests are marked with a 4xx or 5xx error, click on the them to reveal the response of our server. <\/p>\n\n\n\n
    You can make a screenshot and send it to our support team for further assistance.<\/p>\n\n\n\n
    \n
    Delay loading of the Refiner tag<\/h3>\n\n\n\n
    When you want to identify users, it is important that the GTM Data Layer is populated with user data before the Refiner tag is loaded. <\/p>\n\n\n\n
    Depending on the technology your web application us using, the GTM Data Layer might get populated asynchronously and user data might not be available on page load. If this is the case, you need to delay loading the Refiner until user data was provided by your API.<\/p>\n\n\n\n
    Method #1: Fire tag after certain event<\/h4>\n\n\n\n
    The most reliable way to delay loading of the Refiner tag until user data is available is to use a Custom Event Trigger. <\/p>\n\n\n\n
    Your app might already emit an event to the GTM Data Layer which indicates that the user data was loaded, for example “User Data Loaded”. <\/p>\n\n\n\n
    If this is the case, you can use the event as in Triggering section of the Refiner tag as shown in the screenshot below. You can ask your developers if such an event was implemented for your app.<\/p>\n\n\n
    \n
    \"\"<\/figure><\/div>\n\n\n
    Method #2: Use a Timer to delay loading<\/h4>\n\n\n\n
    If no custom event is available in your GTM account which would indicate that user data is available, you can also simply delay the Refiner tag for a couple of seconds. You can do this by using  the Timer Trigger. <\/p>\n\n\n\n
    Usually, delaying the Refiner tag by 2-3 seconds after page load leads to reliable loading of your tag.<\/p>\n\n\n\n
    Follow these steps to implement a time delay for the Refiner tag:<\/p>\n\n\n\n
    1\/ Navigate to Triggers and click on “Create Trigger”.<\/p>\n\n\n
    \n
    \"\"<\/figure><\/div>\n\n\n
    2\/ Choose Timer as the trigger type.<\/p>\n\n\n\n
    \"\"<\/figure>\n\n\n\n
    3\/ Use the following settings for the Timer trigger:<\/p>\n\n\n\n