Integrate AppNavi in Salesforce

This guide describes how to use AppNavi in Salesforce Lightning Experience through the AppNavi browser extension and how to associate usage events with the currently signed-in Salesforce user. No AppNavi loader script, Salesforce API connection, or Salesforce-side integration is required for the described approach.

Important: The user-ID retrieval method below relies on the Salesforce Aura runtime ($A). Its availability is not guaranteed across every Salesforce interface or security configuration. Validate it in your Salesforce environment before rolling out user-level analytics.

Integration Overview

The AppNavi browser extension loads AppNavi on Salesforce pages configured in the AppNavi Portal. Application-level Custom Code attempts to read the ID of the currently signed-in Salesforce user, converts it to Salesforce's canonical 18-character User ID, and passes it to AppNavi Insights through the documented customField_1 API property. AppNavi does not need to receive the user's name or email address. The customer must use the same canonical 18-character ID in their Salesforce export to match users reliably.

AppNavi Integration Options Overview

Integration MethodInterface SupportedIntegration ApproachStrengthsLimitations
AppNavi Browser ExtensionSalesforce Lightning ExperienceLoads AppNavi through the browser extension; reads the signed-in user ID with application-level Custom CodeNo modification of Salesforce application code; no Salesforce API credentials neededRequires the extension and access to the Aura runtime; must be validated for the target Salesforce environment

Prerequisites

  • AppNavi browser extension installed and configured for the correct AppNavi tenant.
  • Salesforce Lightning Experience accessible in a supported Chromium-based browser.
  • Salesforce application created in the AppNavi Portal with the correct Salesforce URL pattern.
  • AppNavi Insights available for the tenant and usage monitoring enabled for the application.
  • Expert Mode enabled for the AppNavi tenant, with Enable Custom Code enabled for the Salesforce application.
  • A Salesforce test account and permission to use the browser developer tools for initial validation.

Salesforce Lightning Integration (Browser Extension)

Steps:

  1. Validate Salesforce user-ID access

    • Sign in to the target Salesforce Lightning Experience environment.
    • Open the browser developer console on a normal Salesforce Lightning page (not the browser's extension service worker).
    • Run:
    window.$A?.get?.("$SObjectType.CurrentUser.Id")

    A successful result is a 15- or 18-character Salesforce User ID starting with 005. The Custom Code below converts it to the canonical 18-character format. If this expression returns undefined, null, or an error, do not proceed on the assumption that the method is supported. See Limitations below.

  2. Configure Salesforce in the AppNavi Portal

    • Navigate to Manage Tenant > Applications > Applications.
    • Create a new application or edit the existing Salesforce application.
    • Set the Application URL and Pattern to the Salesforce Lightning URLs used by your organization (including the relevant production or sandbox domains).
    • Enable the required Insights/analytics configuration.
    • Enable Custom Code. Expert Mode must be active for the tenant.
    • For Code Execution Mode, start with Dynamic. Verify compatibility with the Salesforce site's Content Security Policy (CSP).
  3. Add the Custom Code

    In the Salesforce application's Custom Code section, add the following JavaScript to the application-level code hook that runs when AppNavi starts. Do not add it to an individual guide step or route.

    (function () {
        "use strict";
    
        var MAX_ATTEMPTS = 20;
        var RETRY_INTERVAL_MS = 500;
        var attempts = 0;
    
        // Salesforce's official 15-to-18-character ID conversion uses this alphabet.
        var CHECKSUM_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ012345";
    
        function toCanonicalUserId(value) {
            // Only Salesforce User IDs (prefix 005) are accepted.
            if (typeof value !== "string" ||
                !/^005[A-Za-z0-9]{12}([A-Za-z0-9]{3})?$/.test(value)) {
                return null;
            }
    
            var baseId = value.slice(0, 15);
            var suffix = "";
    
            for (var group = 0; group < 3; group++) {
                var bits = 0;
    
                for (var position = 0; position < 5; position++) {
                    var character = baseId.charAt(group * 5 + position);
                    if (character >= "A" && character <= "Z") {
                        bits |= (1 << position);
                    }
                }
    
                suffix += CHECKSUM_ALPHABET.charAt(bits);
            }
    
            var canonicalId = baseId + suffix;
    
            // Reject inconsistent 18-character values instead of exporting an ID
            // that cannot be matched to Salesforce's CASESAFEID(Id) output.
            if (value.length === 18 && value !== canonicalId) {
                return null;
            }
    
            return canonicalId;
        }
    
        function setSalesforceUserId() {
            try {
                var aura = window.$A;
                var api = window.appnaviApi;
    
                if (!aura || typeof aura.get !== "function") return false;
                if (!api || !api.analytics ||
                    typeof api.analytics.setCustomFieldValue !== "function") {
                    return false;
                }
    
                var canonicalId = toCanonicalUserId(
                    aura.get("$SObjectType.CurrentUser.Id")
                );
                if (!canonicalId) return false;
    
                api.analytics.setCustomFieldValue({
                    customField_1: canonicalId
                });
                return true;
            } catch (error) {
                // Do not interrupt Salesforce or log user identifiers.
                return false;
            }
        }
    
        if (setSalesforceUserId()) return;
    
        var timer = window.setInterval(function () {
            attempts++;
            if (setSalesforceUserId() || attempts >= MAX_ATTEMPTS) {
                window.clearInterval(timer);
            }
        }, RETRY_INTERVAL_MS);
    })();

    How the code works:

    • Reads only the currently signed-in Salesforce User ID; it does not read names, email addresses, or Salesforce business records.

    • Validates the Salesforce User ID (005 prefix) and converts 15-character IDs to the 18-character case-safe format, using Salesforce's checksum algorithm. For 18-character input, it also verifies that the three-character suffix is consistent.

    • Assigns only the canonical 18-character ID to AppNavi's first UBM custom field, using the documented API property customField_1. If validation fails, no ID is assigned.

    • Retries for up to approximately 10 seconds if Salesforce or the AppNavi API is not ready yet.

    • Stops quietly if the ID cannot be obtained; it does not substitute a different user's ID or scrape an ID from the page URL.

    Important: customField_1 supports a maximum of 32 characters. A Salesforce User ID (18 characters) fits within this limit. Make sure customField_1 is not already used for another analytics purpose.

  4. Save and verify the configuration

    • Save the AppNavi application configuration and reload the Salesforce page.
    • Confirm that AppNavi loads through the browser extension.
    • Perform a few non-sensitive UI interactions within Salesforce after the page has loaded.
    • Check the resulting AppNavi Insights/UBM data or export for the first custom field. It must contain exactly 18 characters and start with 005. The column name in an export may differ from the API property customField_1.
    • Compare the field value character for character with the same user's CASESAFEID(Id) value (or the 18-character Id exported by Data Loader).
    • Repeat with at least two distinct Salesforce users. A deployment should not be treated as validated until both IDs match exactly in the AppNavi and Salesforce exports; also test after logout/login and impersonation where relevant.

    Note: With an extension-based integration, window.appnaviApi is not available for manual calls from the ordinary browser developer console. Use the AppNavi Portal Custom Code hook to execute the example and verify the outcome in analytics data. The Salesforce $A expression in step 1 is a separate, Salesforce-side availability check.

Matching Salesforce Users and Licenses on the Customer Side

For license analysis, AppNavi can export measured usage events with the Salesforce User ID stored in the first UBM custom field. The organization can independently export the corresponding user details from Salesforce and match the files locally. Names and email addresses do not need to be imported into AppNavi.

Required matching format: Both exports must contain the same 18-character Salesforce User ID. Do not join a 15-character report ID to the 18-character value saved by AppNavi. Do not change letter case or remove the final three characters.

Recommended Salesforce report export:

  1. In Salesforce Setup > Object Manager > User > Fields & Relationships, create a Formula field with return type Text. Name it, for example, 18-Character User ID. Use the formula:

    CASESAFEID(Id)

    This produces Salesforce's canonical 18-character ID for each User record. Important: CASESAFEID cannot be entered directly as a report-level formula; create the formula field on the User object first.

  2. In Setup > Report Types, create a report type with Users as the primary object if an appropriate report type does not already exist. If license information is needed, add Profile > User License > Name through Add fields related via lookup where supported.

  3. Under Reports > New Report, select the report type and include 18-Character User ID (the new formula field), Full Name, Active, and Profile: User License: Name where available. Do not use the ordinary 15-character User ID report column for matching.

  4. Set appropriate filters (include inactive users for historical analysis where relevant), then export Details Only as CSV.

  5. Verify that every exported User ID has exactly 18 characters, including the original letter case, and that the selected Salesforce organization matches the organization used in AppNavi.

  6. Match the Salesforce CSV to the AppNavi Insights export on the exact 18-character ID, locally in a customer-controlled tool such as Excel Power Query. Review unmatched IDs instead of silently assigning a name by approximate matching.

Salesforce documents that ordinary report columns can display 15-character record IDs, even when reports internally use 18-character IDs for filters. The explicit CASESAFEID(Id) formula field avoids this mismatch.

Alternative: Salesforce Data Loader

An administrator with appropriate access can export the User object to CSV using Data Loader and this SOQL query. Salesforce API results provide 18-character IDs, so no report formula field is needed for this export method:

SELECT Id, Name, IsActive, Profile.Name, Profile.UserLicense.Name
FROM User

Required end-to-end acceptance test:

  • Salesforce test user A: compare CASESAFEID(Id) or Data Loader Id with the value in AppNavi customField_1; it must be an exact string match.
  • Repeat with test user B and verify the resulting ID is different.
  • Verify that the customer CSV contains one row per relevant User ID and inspect any AppNavi IDs with no Salesforce match.
  • Confirm the same behavior after a reload and a fresh login. Do not claim user-level matching is reliable if the Aura API is unavailable in the target environment.

Example of customer-side matching:

AppNavi Salesforce User ID (customField_1, 18 chars)Salesforce Name (customer export only)User License (customer export only)Observed UI Usage
005000000000001AAAExample User ASalesforceUsage events available
005000000000002AAAExample User BSalesforce PlatformNo events in the selected period

Illustrative values only. A missing AppNavi event does not by itself prove a license is unnecessary: consider observation period, extension rollout, access patterns, and any tracking gaps.

License scope: Salesforce User Licenses are only one licensing layer. Permission Set Licenses and feature licenses may need separate Salesforce exports and analysis. The User License field alone does not represent every paid entitlement.

Important Considerations

  • No direct integration: Do not install an-loader.js or add Salesforce-side scripts for this extension-based procedure. Do not run both the loader and the extension for the same application.
  • Salesforce Lightning only: This sample targets Lightning pages with an accessible Aura runtime. Salesforce Classic, Visualforce, Experience Cloud, and other interfaces have not been covered by this procedure.
  • Lightning Web Security: Salesforce restricts access to $A from Lightning Web Components. Availability of $A to the AppNavi page-context Custom Code must therefore be tested; it is not a universal, guaranteed Salesforce integration interface.
  • Content Security Policy: Salesforce or browser restrictions can prevent Custom Code execution even when the extension itself loads. Check the browser console and AppNavi configuration. Avoid weakening security controls without an approved review.
  • Execution order: Usage events captured before the user ID is successfully set cannot be assumed to have the Salesforce ID populated retroactively.
  • Exact ID matching: The sample always emits a validated 18-character Salesforce User ID. Customer exports must also use 18-character IDs (CASESAFEID(Id) for Salesforce reports or Id from Data Loader). Use the same Salesforce organization on both sides. Never remove the checksum suffix or apply case transformations to the 15-character base ID.
  • Fail safely: Invalid IDs and inconsistent 18-character suffixes are rejected, rather than storing a potentially incorrect mapping. Salesforce ID retrieval is a runtime dependency, so successful code execution alone does not establish complete tracking coverage; validate with two real user accounts and match the actual exports before rollout.
  • Session changes: Test logout/login, administrator impersonation (“Log in as”), and organization or account switching. Reload the page after changing users and verify that new events carry the correct ID.
  • Scope: Configure only the intended Salesforce organization domains. Validate sandbox and production separately, including any organization-specific domain changes.
  • Privacy: Salesforce User IDs are pseudonymous identifiers, not anonymous data. Keep the identifying Salesforce export and matching process within the customer's environment and follow applicable privacy, access-control, and employee-monitoring requirements.

Limitations

  • The $A.get("$SObjectType.CurrentUser.Id") approach depends on Salesforce's Aura runtime. It can return no value or become unavailable in a particular Salesforce environment or after a Salesforce platform change.
  • If Salesforce does not expose the current user ID in the page context, there is no universal fallback guaranteed by this extension-only example. Do not infer the signed-in user from a record URL, visible name, or another user's profile ID. Contact AppNavi support to evaluate a separately validated approach.
  • The Custom Code retry period is limited; if initialization takes longer, the ID is not set by this execution. Adjust only after testing the environment. Events captured before the ID is available may remain unmatched; they must not be associated with a user by inference.
  • UI-based usage analytics can show observed interface interactions, but cannot by themselves identify every Salesforce entitlement, backend/API usage, or a user's complete license requirements.

Related Resources


Did this page help you?