Skip to content

Installation Guide

Jump to bottom Edit New page
sokolov-mv edited this page Oct 24, 2025 · 23 revisions

Invitation Manager Installation Guide

Principal Publisher – Service Canada

Non-WET Version

v1.2.2

Version en français

Overview

This installation guide outlines the step-by-step process on how to download, install, and test the non-WET version of the GC Invitation Manager.

The Invitation Manager is a tool that when installed on your website will allow the ability to create and manage invitation pop-ups on your website.

Any department currently onboarded to Canada.ca and using AEM as their CMS does not need this version of the invitation manager installation as they can use the Invitation Manager currently in place on Canada.ca via the Principal Publisher Service Desk.

Download the GC Invitation Manager

To download the GC Invitation Manager tool:

  1. Click the following link to download the invitation-manager.zip file and save to your local drive: https://github.com/ServiceCanada/invitation-manager/archive/refs/tags/v1.2.2.zip
  2. Click to open the .zip file or use any tool to un-zip the file and save contents to your local drive. Within the ZIP file you will find the following:

    • “invitation-manager” > src folder:

      • InvitationManager.js
      • Overlay.js
      • Overlay.css
      • config.json
      • im.json

      A screenshot of a browser popup prompting the user to open or save the 'invitation-manager.zip file'

Installing the GC Invitation Manager

Before you start

System requirements: If your server is not using jQuery library version 2.2.4 or higher you will need to update this.

A note about Staging and Production environments: We recommend you follow this process for your staging/development website before duplicating this on your production website. If you do not have access to a staging/development website, simply go ahead and follow the same steps for your production website with the caveat that any changes made will be live on your site.

Upload files to your server

  1. Copy and paste the “invitation-manager” folder (including its contents: InvitationManager.js, Overlay.js, Overlay.css, config.json, and im.json) anywhere within your web server. Once uploaded these files can remain on your website and will not affect your site performance. The visitor experience will only be affected once a pop-up invitation is activated.

Configure your settings

Save the im.json file

  1. Decide where you want to save the im.json file. Consider easy access for whomever will be creating/editing/removing the pop-ups. If you would like for it to remain in the invitation-manager folder, no action is required. Otherwise, move the file now.
  2. Open the “config.json” file in the “invitation-manager” folder and locate the dbURL parameter. The value should equal the path of the “im.json” file that you determined in step 1.
    • Example: “/invitation-manager/im.json”.
       
     { 
       "dbURL": "/invitation-manager/im.json",
       "Adobe" : "no"
     }

Enable tracking of pop-up invitations

If Adobe Analytics is already implemented on your site, you can enable tracking of the invitation manager pop-ups in the “config.json” file.

  1. Open the “config.json” file in the “invitation-manager” folder and locate the Adobe parameter. The value should equal “yes” or “no”.
    1. Input "Adobe" : "no", if your department site does not have Adobe Analytics tracking implemented: 
           
     { 
       "dbURL": "/invitation-manager/im.json",
       "Adobe" : "no"
     }
    2. Input "Adobe" : "yes", if your department site has Adobe Analytics tracking implemented: 
               
         { 
           "dbURL": "/invitation-manager/im.json",
           "Adobe" : "yes"
         }

To get data on your pop-up invitations, refer to the Pop-Up Invitation Reports User Guide on GCXchange.

If your site does not have Adobe Analytics implemented, you cannot get data on your pop-up invitations. If you would like to have Adobe Analytics implemented on your site, you can learn more by visiting the Adobe Analytics - Implementation on non-Canada.ca websites.

Configuring general settings

  1. Open the “im.json” file. This file is the data source of the Invitation Manager tool and where you will be able create, customize, activate and deactivate all pop-up invitations. This file will need to be updated with your departmental data and customized for your website.

    The “im.json” file is comprised of two sections:

    1. General settings: this section is used to customize the general application settings of the invitation manager tool. The following parameters will need to be updated: 
            
      "settings":
      {
        
        "duration-delay": Number_of_days,
        "page-probability": Value1_less_than_one,
        "site-probability": Value2_less_than_one,
        "blacklist": [
          {"url" : "https://blacklist1.com"},
          {"url" : "https://blacklist2.com"}
         ],
        "whitelist": [
          { "url" : "^whitelistDomain.com\/"}
         ]
        
      },

      Example:

            
      {
        "settings":
        {
          "duration-delay": 15,
          "page-probability": 0.7,
          "site-probability": 0.3,
          "blacklist": [{"url" : ""}],
          "whitelist": [{ "url" : "^servicecanada.github.io\/"}]
        },
      • "duration-delay" value contains the number of days in between when the visitor saw the original pop-up invitation and when they will see the next pop-up invitation on your site(s). This number must be greater than zero, and less than or equal to 365.
        • We recommend 15 days.
      • "page-probability" value contains the rolling probability a visitor will see page level popup invitations. This number must be greater than 0.0, and less than or equal to 1.0. Additionally the sum of both page and site probability must not exceed 1.0 (for 100%).
        • We recommend 0.7 (for 70%)
      • "site-probability" value contains the rolling probability a visitor will see a site level popup invitations. This number must be greater than 0.0, and less than or equal to 1.0. Additionally the sum of both page and site probability must not exceed 1.0 (for 100%).
        • We recommend 0.3 (for 30%)
      • "blacklist" value contains an array of URLs that represent the blacklist. They are the URLs for pages you do not want pop-ups invitations to appear on.
        • Add each URL to the array following the syntax exampled below: 
                      
              "blacklist" : [ 
                { "url" : "www.canada.ca/en/blanklistexample1.html"},
                { "url" : "www.canada.ca/en/blanklistexample2.html"},
                { "url" : "www.canada.ca/en/blanklistexample3.html"} 
              ],
      • "whitelist" value contains an array of URLs that represent the whitelist. A list of server domains and/or URLs that you want the popup invitation to appear on.
        • Add each of your domains to the array following the syntax exampled below: 
                      
              "whitelist" : [ 
                { "url" : "^www.canada.ca\/" },
                { "url" : "^www1.canada.ca\/" },
                { "url" : "^servicecanada.gc.ca\/"} 
              ]
    2. Surveys: this section is comprised of parameters used to create, customize the html and activate/deactivate the invite(s) that will appear on your site. 
      "surveys" : [
{
  "id" : "1",
  "title-en" : "English Title",
  "title-fr" : "Titre Francais",
  "body-en" : "<p>English Description.</p>",
  "body-fr" : "<p>Description en Francais.</p>",
  "link-en" : "https://survey1_link_en",
  "link-fr" : "https://survey1_link_fr",
  "start-on" : "YYYY-MM-DDTHH:mm:ss",
  "end-on" : "YYYY-MM-DDTHH:mm:ss",
  "type" : "Entire site",
  "probability" : Value_less_than_one,
  "yes-en" : "<strong>Yes, <span class='wb-inv'>I will take the exit survey </span>after my visit.</strong>",
  "yes-fr" : "<strong>Oui, <span class='wb-inv'>je vais participer au sondage de départ </span>après ma visite.</strong>",
  "no-en" : "No, <span class='wb-inv'>I do not want to take the exit survey, </span>thank you.",
  "no-fr" : "Non, <span class='wb-inv'>je ne veux pas participer au sondage de départ, </span>merci.",
  "close-en" : "Close: Exit survey (escape key)",
  "close-fr" : "Fermer : Sondage de fin de visite (touche d&apos;échappement)",
  "name" : "Survey_Name",
  "survey-urls" : [
    {"site" : "^site_domain.com"}
  ]
},
{
  "id" : "2",
  "title-en" : "English Title",
  "title-fr" : "Titre Francais",
  "body-en" : "<p>English Description. </p>",
  "body-fr" : "<p>Description en Francais. </p>",
  "link-en" : "http://www1.canada.ca/en/contact/sc_account.html?referrer=logout",
  "link-fr" : "http://www1.canada.ca/fr/contact/mon_dossier_sc.html?referrer=logout",
  "start-on" : "YYYY-MM-DDTHH:mm:ss",
  "end-on" : "YYYY-MM-DDTHH:mm:ss",
  "type" : "Page",
  "probability" : Value_less_than_one,
  "yes-en" : "<strong>Yes,  <span class='wb-inv'>I will take the exit survey </span> after my visit.</strong>",
  "yes-fr" : "<strong>Oui, <span class='wb-inv'>je vais participer au sondage de départ </span> après ma visite.</strong>",
  "no-en" : "No, <span class='wb-inv'>I do not want to take the exit survey, </span> thank you.",
  "no-fr" : "Non, <span class='wb-inv'>je ne veux pas participer au sondage de départ, </span> merci.",
  "close-en" : "Close: Exit survey (escape key)",
  "close-fr" : "Fermer : Sondage de fin de visite (touche d&apos;échappement)",
  "name" : "Survey_Name",
  "survey-urls" : [
    { "url" : "https://domain_example/example-eng.html"},
    { "url" : "https://domain_example/example-fra.html"}
  ]
}
]

    The surveys array is pre-built with the following blank templates. How to customize these templates and publish your own invitation popup’s is covered in the Invitation Manager Publishing Guide:

    • Site level invite 
              {
          "id" : "1",
          "title-en" : "English Title",
          "title-fr" : "Titre Francais",
          "body-en" : "<p>English Description.</p>",
          "body-fr" : "<p>Description en Francais.</p>",
          "link-en" : "https://survey1_link_en",
          "link-fr" : "https://survey1_link_fr",
          "start-on" : "YYYY-MM-DDTHH:mm:ss",
          "end-on" : "YYYY-MM-DDTHH:mm:ss",
          "type" : "Entire site",
          "probability" : Value_less_than_one,
          "yes-en" : "<strong>Yes, <span class='wb-inv'>I will take the exit survey </span>after my visit.</strong>",
          "yes-fr" : "<strong>Oui, <span class='wb-inv'>je vais participer au sondage de départ </span>après ma visite.</strong>",
          "no-en" : "No, <span class='wb-inv'>I do not want to take the exit survey, </span>thank you.",
          "no-fr" : "Non, <span class='wb-inv'>je ne veux pas participer au sondage de départ, </span>merci.",
          "close-en" : "Close: Exit survey (escape key)",
          "close-fr" : "Fermer : Sondage de fin de visite (touche d&apos;échappement)",
          "name" : "Survey_Name",
          "survey-urls" : [
            {"site" : "^site_domain.com"}
          ]
        },
    • Page level invite 
              {
          "id" : "2",
          "title-en" : "English Title",
          "title-fr" : "Titre Francais",
          "body-en" : "<p>English Description.</p>",
          "body-fr" : "<p>Description en Francais.</p>",
          "link-en" : "http://www1.canada.ca/en/contact/sc_account.html?referrer=logout",
          "link-fr" : "http://www1.canada.ca/fr/contact/mon_dossier_sc.html?referrer=logout",
          "start-on" : "YYYY-MM-DDTHH:mm:ss",
          "end-on" : "YYYY-MM-DDTHH:mm:ss",
          "type" : "Page",
          "probability" : Value_less_than_one,
          "yes-en" : "<strong>Yes,  <span class='wb-inv'>I will take the exit survey </span> after my visit.</strong>",
          "yes-fr" : "<strong>Oui, <span class='wb-inv'>je vais participer au sondage de départ </span> après ma visite.</strong>",
          "no-en" : "No, <span class='wb-inv'>I do not want to take the exit survey, </span> thank you.",
          "no-fr" : "Non, <span class='wb-inv'>je ne veux pas participer au sondage de départ, </span> merci.",
          "close-en" : "Close: Exit survey (escape key)",
          "close-fr" : "Fermer : Sondage de fin de visite (touche d&apos;échappement)",
          "name" : "Survey_Name",
          "survey-urls" : [
            { "url" : "https://domain_example/example-eng.html"},
          { "url" : "https://domain_example/example-fra.html"}
          ]
        }

Add the Invitation Manager code to your website pages

Each page on your website must be updated with the following html code in order to reference the invitation manager files.

  1. Add the following code to the

    of your webpages. This will link to the "Overlay.css" file.

    <!--InvitationManager Files -->

    <link rel="stylesheet" href="/invitation-manager/Overlay.css">

    <!-- End InvitationManager Files -->

  2. Add the following code to the closing

    of your web pages. This will link to the "Overlay.js", and "InvitationManager.js" files.

    <!-- InvitationManager Files -->

    <script src="/invitation-manager/Overlay.js"></script>

    <script src="/invitation-manager/InvitationManager.js"></script>

    <!-- End InvitationManager Files -->

Testing the Invitation Manager

In order to test your installation you will need to create and publish a test invite. Refer to the Invitation Manager Publishing Guide for detailed instructions on how to do this for your server(s).

Before you test:

  • Identify the hostname and/or page(s) you wish to test an invite on. This will need to be done on both your staging and production servers (we recommend it being a page with little to no traffic)
  • You will need to create a "page" level and “site” level invite for testing.

General Testing:

Steps to test:

  1. Publish test invite

  2. Generate html query string

    • Based on the test invites you created, modify the following URL query string to reflect the survey id and the scope type you inputted for your survey invite:

        ?logim=1&im_scope=page or site&im_surveyid=##&im_nocookiecheck=1&im_nodatecheck=1

  3. Review page(s)

    • Open your browser and navigate to the page that you included in the survey-urls array of the invite and include the URL query string at the end:

      Example:

        https://exampledomain.com/en/1.html?logim=1&im_scope=page&im_surveyid=1&im_nocookiecheck=1&im_nodatecheck=1

  4. Review the invite

    • Invite appears:

      • If the invite appears on your webpage, then you have successfully installed the invitation manager and published a survey invite on your server.
      • Be sure to review the text of the invite to ensure it is displayed properly on your webpage. Image showing an example of a invitation manager popup

    • Invite does not appear:

  5. Clear the test invite(s) you created from the “im.json” file.

Analytics Testing:

If Adobe Analytics is implemented on your site and you have enabled tracking of the invitation manager pop-ups in the “config.json” file, the following test can be performed in addition to the General Testing mentioned above. The Analytics Testing is to verify that your website is sending data to Adobe Analytics. For more information on analytics testing, refer to the Adobe Analytics Implementation - Testing Process Manual.

Steps to test:

  1. Open your browser and type into the navigation bar the page URL that you included in the survey-urls array of the invite and add the following to the end of your URL: * The testing URL query string to generate the pop-up on demand (refer to General Testing section) * The query string &logdtm=1 to display the collected analytics data (beacon) in the console.

    Example:

    https://exampledomain.com/en/1.html?logim=1&im_scope=page or site&im_surveyid=##&im_nocookiecheck=1&im_nodatecheck=1&logdtm=1

  2. Open the Developer Tools and ensure that the console tab is open with persist logs (or preserve logs) enabled, then navigate to your website using the URL in step 1

  1. Methods to open the Developer Tools:
    1. Hit F12 on your keyboard to open the Developer Tools and select the Console tab. OR
    2. Right click anywhere on the page and select “Inspect” in the dropdown menu that appears. Then select the Console tab. OR
    3. Open the Options menu in your browser and find the Web Developer Tools
  2. Methods to enable persist logs to ensure continuation of the beacons
    1. Open the Console settings and ensure a check ✓ appears beside Persist Logs.

      Chrome/Edge

      Image showing the steps to activate the Preserve Log in Chrome browser - Web Developer Tools - Console

      Firefox

      Image showing the steps to activate the Persist Logs in Firefox browser - Web Developer Tools - Console

      Safari

      Image showing the steps to activate the Persist Logs in Safari browser - Web Developer Tools - Console

  1. Within the console tab, the following information should be displayed once the invite appears. Double check to make sure the information corresponds with the table below.

    ADOBE ANALYTICS CLICK EVENT

    Events event58
    v1 Local day – collected from the settings of your browser/device
    v2 Local time rounded to the nearest 30min time block – collected from the settings of your browser/device
    v4 Device type (i.e. desktop or mobile)
    v5 Language of the page – collected from the metadata of the page. If no metadata exists value will return blank
    v11 Title of the page – collected from the metadata of the page. If no metadata exists value will return blank
    v12 URL of the page
    v15 Creator of the page – collected from the metadata of the page. If no metadata exists value will return blank
    v57 The unique name identifying the invitation popup (i.e. Dept. abbreviation – Survey name – Date) in the im.json file.
    v65 AppName for the website – collected from the metadata of the page. If no metadata exists value will return blank
    v75 Analytics code version used for analytics tracking

  2. Click the “Yes, after my visit” button on the invite. On click, the following information should be displayed in the console tab. Double check to make sure the information corresponds with the table below. Image showing an example of a invitation manager popup Yes Button

    ADOBE ANALYTICS CLICK EVENT

    Events event57
    v1 Local day – collected from the settings of your browser/device
    v2 Local time rounded to the nearest 30min time block – collected from the settings of your browser/device
    v4 Device type (i.e. desktop or mobile)
    v5 Language of the page – collected from the metadata of the page. If no metadata exists value will return blank
    v11 Title of the page – collected from the metadata of the page. If no metadata exists value will return blank
    v12 URL of the page
    v15 Creator of the page – collected from the metadata of the page. If no metadata exists value will return blank
    v57 The unique name identifying the invitation popup (i.e. Dept. abbreviation – Survey name – Date) in the im.json file.
    v65 AppName for the website – collected from the metadata of the page. If no metadata exists value will return blank
    v75 Analytics code version used for analytics tracking

  3. Repeat the testing steps above for your French pages.

Post-installation

Publish pop-ups

Now that you have the Invitation Manager installed on your website, you are now ready to begin publishing pop-up invitations. Refer to the Invitation Manager Publishing Guide for detailed instructions.

Get support

If you are having trouble with the installation and need support, contact us via the Principal Publisher Service Desk, and select the following categories when submitting your request:

  • Category: Website surveys
  • Sub-category: Invitation Manager: Support
Add a custom footer
Add a custom sidebar

Clone this wiki locally