NAV Navbar
javascript
  • Introduction
  • Getting Started
  • API Endpoints
  • The GA Data object
  • Introduction

    Welcome to the userID Client Library and API documentation. We recommend using the Quick Start Guide to get started with userID.

    Users who want to implement their own session control also have access to userID's API Endpoints.

    Getting Started

    Client Library

    The userID client library is a javascript wrapper around the userID API. The client library snippet will automatically load and inject the library into your web application. Below is an explanation of the required and optional parameters used with the client library snippet.

    !function(e){var t=window,i=document,s=e.endpoint||"//app.userid.io/js/userid.js",u=e.globalFuncName||"uid";t.UserIdFuncName=u,t[u]=t[u]||function(){(t[u].queue=t[u].queue||[]).push(arguments)},t[u].endpoint=s,t[u].account=e.account,t[u].properties=e.properties,t[u].uidAtt=e.uidAtt||"email",t[u].cds=e.cds,t[u].isReadyTimer=setTimeout(function(){t.dataLayer.push({event:"userIdReady"})},1500),scriptTag=i.createElement("script"),scriptTag.async=1,scriptTag.src=s,i.body.insertBefore(scriptTag,i.body.childNodes[0])}
    ({
      account: 'YOUR_ACCOUNT_ID',
      endpoint: '//app.userid.io/js/userid.js',
      cds: [1, 2],
      globalFuncName: "uid",
      properties: ['UA-XXX-XXXX'],
      uidAtt: "email",
    });
    
    Option Type Default Description
    account String undefined Your userID account ID required
    cds Array undefined An array of custom dimension indices used for Google Analytics. If set, the first dimension will receive a Google Analytics Client ID. The second dimension will receive a hashed value used to identify that user. optional
    endpoint String '//app.userid.io/js/userid.js' Client library source code required
    globalFuncName String 'uid' The function name used to invoke functions on the client library object. By default this function will be set on the window. optional
    properties Array undefined An array of Google Analytics property IDs required
    uidAtt String 'email' The attribute used to identify a user. The client library will automatically look for this attribute as a query paremeter in the URL. optional

    Session Management

    The userID client library automatically handles sessions using the public userID session endpoints. Session management follows Google Analytics session definitions;

    API Endpoints

    The userID client library functionality is built around the following RESTful endpoints:

    Check Session and Set Session are not required for using userID. If you plan on handling sessions manually and want to take advantage of userID functionality jump to Get or Create.

    Redirect and Encode

    An unencoded email in a url is a potential exposure of PII to third party tracking scripts. The redirect endpoint is provided to address this issue. The endpoint will encode an email (or other specified query parameter) and redirect to a destination url while keeping other tracking parameters in tact.

    HTTP Request

    GET https://app.userid.io/api/r

    URL Parameters

    Parameter Description
    account_id Your userID account ID required
    destination_url The final url for clicked links required
    email This key can be overridden by uid_att required/replaced by uid_att
    uid_att Used to specify a key, other than email for the user id attribute field optional
    other parameters utm_source,utm_medium,etc. optional

    Check Session

    The check session endpoint will check all userID managed sessions for possible session changes. A session change is based on how a web session is defined in Google Analytics.

    When an existing session has been identified as a new session, userID will process the existing session and start a new one.

    HTTP Request

    GET https://app.userid.io/api/sessions/check-session

    $.ajax({
      type: 'GET',
      url: 'https://app.userid.io/api/sessions/check-session',
      data: {
        account_id: 'YOUR_ACCOUNT_ID',
        gclid: '',
        google_analytics_client_id: ''
        referrer: '',
        utm_campaign: '',
      },
      success: (response) => {
        console.log(response);
      },
    });
    

    URL Parameters

    Parameter Description
    account_id Your userID account ID required
    gclid The current Google AdWords Click ID optional
    google_analytics_data An array of Google Analytics data pertinent to userID. See the GA data object required
    referrer The document referrer. Usually window.document.referrer optional
    utm_campaign The current UTM campaign parameter optional

    Set Session

    Set a user ID session in userID's session management system.

    HTTP Request

    GET https://app.userid.io/api/sessions/set-session

    const gaData = {
      properties: {
        'UA-XXXXXXX': '1234.1234',
      },
      cds: [1, 2],
    };
    
    $.ajax({
      type: 'GET',
      url: 'https://app.userid.io/api/sessions/set-session',
      data: {
        account_id: 'YOUR_ACCOUNT_ID',
        gclid: '',
        google_analytics_data: JSON.stringify(gaData),
        referrer: '',
        uid_value: '',
        utm_campaign: '',
      },
      success: (response) => {
        console.log(response);
      },
    });
    
    URL Parameter Description
    account_id Your userID account ID required
    gclid The current Google AdWords Click ID optional
    google_analytics_data An array of Google Analytics data pertinent to userID. See the GA data object required
    referrer The document referrer. Usually window.document.referrer optional
    uid_value The unique identifer associated with a user on your website. This could be something like an email address or login id optional
    utm_campaign The current UTM campaign parameter optional

    Get or Create

    Get or create a userID for a user. As name implies, if the required parameters do no not match an existing user's properties, a new user will be created.

    HTTP Request

    GET https://app.userid.io/api/google-analytics-users/get-or-create

    $.ajax({
      type: 'GET',
      url: 'https://app.userid.io/api/google-analytics-users/get-or-create',
      data: {
        account_id: 'YOUR_ACCOUNT_ID',
        uid_value: 'some@user.com',
        google_analytics_property_id: 'UA-XX-XXXX',
        google_analytics_client_id: '1234.1234',
      },
      success: (response) => {
        console.log(response);
      },
    });
    

    URL Parameters

    Parameter Description
    account_id Your userID account ID required
    google_analytics_client_id The Google Analytics Client ID associated with a user. See Getting the Client ID from the cookie required
    google_analytics_property_id The Google Analytics Property ID associated with the website using userID optional
    uid_value The unique identifer associated with a user on your website. This could be something like an email address or login id optional

    The GA Data object

    The google_analytics_data object is made up of values forwarded to Google Analytics.

    When the userID algorithm determines a user's session is ending, userID processes that session and makes a hit to Google Analytics using the data provided in the GA Data object.

    In most cases a website uses a single GA property ID. In the case of multiple properties, use the property ID as a key on the properties object while passing the Google Analytics Client ID as the value.

    Constructing the object

    Property Type Description
    cds Array An array of up to two integers which represent a Google Analytics custom dimension index. The GA userID will be supplied to the first custom dimension index and the userID value will be supplied to the second custom dimension in the array optional
    properties Object An object comprised of Google Analytics Property IDs as keys and the Google Analytics Client ID for that property required
    const gaData = {
      properties: {
        'UA-XXXXXXX': '1234.1234',
      },
      cds: [1, 2],
    };