Gamify Configuration Guide

Step 2: Choose User Attribute to Group Users By

In order to divide all users into groups that will compete with each other based on their organizational information (department, office, etc.), select which user profile attribute you would like to group users by.

This information will be taken from SharePoint user profiles. If you have created custom profile properties you can also use them.

Gamify Configuration Screen: Step 2

Step 3: Add The Gamify Tracking Code To Your Sites

This step allows you to add the JavaScript tracking code to each of your sites. 

Select one of the following options to add the tracking code to specific sites or deploy it on all selected site collections and their subsites automatically.

Install the tracking code automatically using a SharePoint App (recommended)

Select this option to add the tracking code to all selected sites (in "Choose Sites to Integrate with" step) automatically using a SharePoint App.

Note: This is the recommended method for installing the tracking code on all selected site collections, including automatically enabling it for newly created subsites under the selected site collections. 

Create a SharePoint App

1. Login to SharePoint with the Global Administrator account.
2. Navigate to https://<Admin Center>/_layouts/15/AppRegNew.aspx (e.g. https://company-admin.sharepoint.com/_layouts/15/AppRegNew.aspx).
3. Create a 'full-trust' app with the following details:
   1. Client ID and Secret - click Generate to automatically create a client ID and secret and copy these values.
   2. Title - CardioLog Analytics Tracking Deployment
   3. App Domain - localhost
   4. Redirect URI - https://localhost
4. Navigate to https://<Admin Center>/_layouts/15/AppInv.aspx (e.g. https://company-admin.sharepoint.com/_layouts/15/AppInv.aspx).

5. Paste the client ID into the App Id field. Click Lookup. The existing values for Title, App Domain and Redirect URL should appear.

6. Enter the following XML into the App's Permission Request XML field to specify required permissions. Then click Create.

   <AppPermissionRequests AllowAppOnlyPolicy="true">     <AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="FullControl" />     <AppPermissionRequest Scope="http://sharepoint/content/sitecollection" Right="FullControl" />     <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web" Right="FullControl" /> </AppPermissionRequests>

7. You will be prompted to approve permissions for the app. Click Trust It.

8. Once the App is created, return to the Gamify configuration screen and enter the details of the Client ID and Client Secret in the "Add the Gamify Tracking Code to your Sites" step.

9. Select Automatically track all subsites including newly created ones in order to automatically enable tracking for newly created subsites under the selected site collections (in "Choose Sites to Integrate with" step).

10. Select Notify me when client secret expires or is not working in order to receive an email alert to the specified email address. Follow these steps in order to renew the SharePoint App client secret if needed.
11. Click Save.
12. Click Install Tracking to install the tracking code on all selected site collections and their subsites.
    
    
    
    Note: This step may take a while to complete, depending on the amount of selected sites. Follow the installation progress on the screen.
    
    
13. Click View installation report to view a detailed report of the installation progress. Click the top left down arrow icon to export the report to CSV.

Renew SharePoint App Client Secret

1. Execute the following PowerShell commands with the SharePoint Online Global Administrator account. 

2. Edit the "Client ID" and use the Client ID value from the Gamify configuration screen in "Add the Gamify Tracking Code to your Sites" step. 

   Connect-MsolService $clientId = "Client ID" $keys = Get-MsolServicePrincipalCredential -AppPrincipalId $clientId -ReturnKeyValues false $keys Remove-MsolServicePrincipalCredential -KeyIds $keys.KeyId -AppPrincipalId $clientId

3. In the same PowerShell window, execute the following PowerShell commands in order to generate a new client secret.

   $bytes = New-Object Byte[] 32 $rand = [System.Security.Cryptography.RandomNumberGenerator]::Create() $rand.GetBytes($bytes) $rand.Dispose() $newClientSecret = [System.Convert]::ToBase64String($bytes) $dtStart = [System.DateTime]::Now $dtEnd = $dtStart.AddYears(1) New-MsolServicePrincipalCredential -AppPrincipalId $clientId -Type Symmetric -Usage Sign -Value $newClientSecret -StartDate $dtStart -EndDate $dtEnd New-MsolServicePrincipalCredential -AppPrincipalId $clientId -Type Symmetric -Usage Verify -Value $newClientSecret -StartDate $dtStart -EndDate $dtEnd New-MsolServicePrincipalCredential -AppPrincipalId $clientId -Type Password -Usage Verify -Value $newClientSecret -StartDate $dtStart -EndDate $dtEnd $newClientSecret

4. Copy the new client secret value and update it in the Gamify configuration screen in the "Add the Gamify Tracking Code to your Sites" step and click Save.

Install the tracking code automatically using a PowerShell script 

Select this option to add the tracking code to all selected site collections (in "Choose Sites to Integrate with" step) automatically using a PowerShell script.
Note: It is required to execute the PowerShell script every time you create new sites under the selected site collections in order to enable tracking for them.

1. Click CardioLog Analytics Tracking Deployment package to download the deployment package from the "Add the Gamify Tracking Code to your Sites" step in the Configuration page.
   The package includes a PowerShell script that deploys the tracking agent wsp solution, modern sites integration app and the Java Script tracking code on all selected site collections.
2. Right click the downloaded package zip file, select Properties > General and click on "Unblock" before unzipping it.
3. Execute the Run_Script.ps1 script in Windows PowerShell (do not use Windows PowerShell ISE version). Make sure to close all browser windows on your machine before executing the script.
   Note: You must have the MS Online module installed and the credentials of the SharePoint Online global administrator.

Install the tracking code manually

Select this option to add the tracking code to specific sites manually.

1. Click CardioLog Analytics Tracking solution to download the deployment package from the "Add the Gamify Tracking Code to your Sites" step in the Configuration page.
2. Right click the downloaded package zip file, select Properties > General and click on "Unblock" before unzipping it.
3. Temporarily allow custom scripts during the installation in order to add the JavaScript tracking code and Tracking Agent application (sppkg for modern sites, wsp solution for classic sites) to your app catalog and all of the site collections you wish to monitor.
   Execute the following commands in the SharePoint Online Management Shell (edit your SharePoint admin center and site collection URLs). 

   1. Connect to SharePoint Online Admin Center with the SharePoint Online Global Administrator account:

      Connect-SPOService -Url https://company-admin.sharepoint.com

   2. Get the current value of the Custom Scripts setting DenyAddAndCustomizePages for each site collection you wish to monitor and for your App Catalog:

      Get-SPOsite https://company.sharepoint.com | Select DenyAddAndCustomizePages

   3. If the current value of DenyAddAndCustomizePages is Enabled, set it to Disabled:

      Set-SPOsite https://company.sharepoint.com -DenyAddAndCustomizePages 0

   4. Disconnect from SharePoint Online: 

      Disconnect-SPOService

4. Browse to your SharePoint Online site collection Solution Gallery. The gallery should be found at the following address (replace the site collection root URL https://company.sharepoint.com/sites/site with yours): https://company.sharepoint.com/sites/site/_catalogs/solutions/forms/allitems.aspx
5. From your Solution Gallery, click Upload Solution > Choose File. Then select the CAI.wsp  solution file which can be found in the deployment package and click Activate.
6. If you are presented with a request for access, make sure you have temporarily allowed custom scripts for your site collection and app catalog.

7. Once the solution is installed, return to the Gamify configuration screen and click Copy script to copy the JavaScript tracking code.

8. Browse to CardioLog Analytics Integration solution configuration page. The page should be found at the following address (replace the site collection root URL https://company.sharepoint.com/sites/site with yours): https://company.sharepoint.com/sites/site/CardioLogAnalytics/Configuration.2.0.8.0.aspx

9. Paste the tracking code copied from the "Add the Gamify Tracking Code to your Sites" step and click OK.

10. In order to track SharePoint Online modern sites and pages, install the Tracking Agent App:

    1. Click CardioLog Analytics Tracking Agent App for modern sites to download the Tracking Agent App.

    2. Upload the CardioLogTrackingAgentAddin.sppkg app to the SharePoint Admin apps > App Catalog > Apps for SharePoint > New.

    3. Click Deploy (do NOT select "Make this Solution available to all sites in the organization")

    4. Add the App to your site collection and to all of its subsites under Site Contents > New App

    5. Click on Apps from your organization and click CardioLog Tracking Agent (it will be installed automatically)

11. After the installation is complete, revert the changes performed in step 3 (if any) and disable custom scripts.

    Connect-SPOService -Url https://company-admin.sharepoint.com Set-SPOsite https://company.sharepoint.com -DenyAddAndCustomizePages 1 Disconnect-SPOService

Inject the tracking code to all site pages yourself

Select this option to inject the tracking code manually to your site pages.

1. Click Copy script to copy the JavaScript tracking code to the clipboard.
2. Paste the tracking code into the <head> section of each site page you would like to track.

Step 4: User Roles Management 

In order to access the Gamify Admin Dashboard, select the users you would like to grant the admin role to. 

1. Connect with an account that is a global administrator in your Office 365 tenant. This account will be used in order to approve the required permissions for the Gamify Azure AD App to manage user roles in Azure AD.
   
   
   Gamify Configuration Screen: Step 4
   
   
2. Click Accept to approve the required permissions.
3. In order to grant the admin role to a user, enter the user principal name (UPN) and click Save.
   
   
   Gamify Configuration Screen: Step 4

Step 5: Game Settings

In this step, you can set up the game settings, including scheduling game rounds and calculating scores. You can assign points for various user activities like viewing content, creating content, and liking content. Points can be awarded to different personas—Explorer, Engager, and Contributor—based on their usage patterns. Additionally, content owners can earn points when users interact with their content by liking or commenting on it, through "Derived" events. The users' scores are determined by their overall activity within SharePoint.

User Personas

Explorer - Mainly consumes content. For example, views content and performs searches.
Engager - Mainly interacts with content. For example, likes content, rates content and follows content.
Contributor - Mainly contributes content. For example, writes posts and comments, uploads documents, etc.

Please note that after the initial setup, there will be a "gathering period" during which the system will collect data about your users. This data will be used to group and profile users based on their usage habits and assign them to personas. By default, the gathering period is set to 30 days (configurable). The first game round can be scheduled immediately after this period.

1. When there is no active game round, configure a new game round in the Next Round Settings.
2. Set the Start Date and End Date for the game.
3. Click on Add event to include the user activities for which you'd like to allocate points. For example viewing content, creating content, liking content etc. You can allocate different points to particular actions within each persona, enabling diverse weightings tailored to the user's profile and typical usage patterns. 
4. Click Save.
   
   
   Gamify Configuration Screen: Step 5
   
   
5. During an ongoing game round, you'll find its settings displayed under Current Round Settings. For upcoming rounds, you can adjust the settings under Next Round Settings.
   
   
   Gamify Configuration Screen: Step 5