Skip to end of metadata
Go to start of metadata

The configuration contains a few simple steps that walk you through setting up Augmented Analytics.


Augmented Analytics Configuration Screen

Step 1: Choose Sites to Integrate with

In order to display the Augmented Analytics reports in SharePoint, select which site collections you would like to integrate with and display the reports on.

The Augmented Analytics reports are only available on sites once the tracking code is deployed for them in the "Add the Augmented Analytics Tracking Code to your Sites" step.

 

  1. Click Connect.
    Note: A global administrator account is required in order to consent to the permissions required to read items from all site collections and read users' full profiles. 



  2. Click Accept to approve the required permissions.
    Note: An App will be created in your Azure Active Directory. It may take up to 24 hours for changes to take effect.

  3. With this section expanded, you should see all of your available SharePoint Online site collections.


    Augmented Analytics Configuration Screen: Step 1

  4. Select all the sites you would like to integrate with.
  5. You can also search for site collections by typing in their name in the search bar.
  6. Select the button next to each site you would like to integrate with.
  7. Click Save to confirm your selection.

You can go back and add more sites or remove sites from your selection at any point.
Note: The number of site collections available for selection in your subscription is limited.

Please note that the integration process for large site collections may take a few hours up to a few weeks, depending on the environment size.


Step 2: Choose Permission Level to Grant Access By

In order to grant access to the Augmented Analytics reports, select which permission level in SharePoint you would like to grant access to.

Only users with this exact permission level in SharePoint will see the Augmented Analytics reports on the selected site collections.


Augmented Analytics Configuration Screen: Step 2

Step 3: Add the Augmented Analytics 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 Augmented Analytics configuration screen and enter the details of the Client ID and Client Secret in the "Add the Augmented Analytics 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 Augmented Analytics configuration screen in "Add the Augmented Analytics Tracking Code to your Sites" step. 

    Connect-MsolService
    $clientId = "Client ID"
    $keys = Get-MsolServicePrincipalCredential -AppPrincipalId $clientId
    $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 Augmented Analytics configuration screen in the "Add the Augmented Analytics 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 Augmented Analytics 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 Augmented Analytics 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 Augmented Analytics 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 Augmented Analytics 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.
  • No labels