User Identification How Hawk tells your users apart

Automatic User Identification
Automatic User Identification
Automatic User Identification

User identification functionality can be configured on the Identify Users tab of the Sites settings menu.

If your site allows users to log in to individual accounts, your analytics results with Hawk will greatly improve if Hawk can identify which user is which. User identification allows Hawk to associate multiple sessions, from different devices and ip addresses, with the same user. Also, it increases the convenience of knowing who’s who on the Hawk platform.

Choose between automatic and manual user identification using the Identify users automatically slider.

Manual User Identification

When Identify users automatically is turned off, Hawk will show a description of three methods you can call on the hawk object. You can use these methods to communicate with Hawk from within your own JavaScript code. The Manual User Identification section will explain what each method expects.

  • trackEvent('signup', {...}) Use this method to let Hawk know when a user creates a new account.
  • setUser({...}) Use this method to tell Hawk which user this is.
  • setUser(null)

Automatic User Identification

There are two automatic user identification features that can be configured: Logged In User and New Account Sign Up. Logged In User helps Hawk keep up to date with the current user as they navigate your site. New Account Sign Up registers new users as they create accounts on your site.

Logged In User Identification

API Call
Hawk User Identification By API Call
User Identification by API Call

Hawk hooks into window.fetch and window.XMLHttpRequest to look at your site’s traffic (for technical details, see here.)
If you let Hawk know what backend endpoint your frontend code calls to retrieve the currently logged in user, it can find the user’s information without you having to write any extra code.

For an explanation of how to use the API call filters, see the How the API Call Filter Works section below.

Make sure to tell Hawk where in the response object the user data can be found. Dot syntax is used to navigate object structure.

  • email
  • name
  • phone
  • uniqueIdrequired
  • username
JWT
Hawk User Identification by JWT
User Identification by JWT

Use the drop-down menu to let Hawk know where it can find the JWT:

  • a cookie
  • localStorage
  • sessionStorage

Make sure to tell Hawk where in the JWT object the user data can be found. Dot syntax is used to navigate object structure.

  • email
  • name
  • phone
  • uniqueId (required)
  • username
Custom JS
Hawk User Identification By Custom JS
User Identification by Custom JS

Optionally, you can enter a custom JavaScript function. Hawk will run this function to determine the identity of the currently logged in user.

If a user is logged in, your function should return an object with the following properties:

  • email
  • name
  • phone
  • uniqueId (required)
  • username

Hawk will pass your function whatever user information it previously received, if any.

New Account Sign Up Identification

Hawk identifies new sign ups by hooking into window.fetch and window.XMLHttpRequest to look at your site’s traffic (for technical details, see here.)
If you let Hawk know what backend endpoint your frontend code calls when a user signs up, it can find the user’s information without you having to write any extra code.

For an explanation of how to use the API call filters, see the How the API Call Filter Works section below.

Make sure to tell Hawk where in the response object the user data can be found. Dot syntax is used to navigate object structure. Choose between request and response to specify whether the particular field is found in the request object or the response object.

  • coupon
  • email
  • name
  • phone
  • plan
  • uniqueId (required)
  • username

How the API Call Filter Works

You provide Hawk with a set of rules that it will use to distinguish your site’s user information network traffic from all the rest.
All vs. Any This is the difference between logical and and logical or. You might use Any to let us know about multiple different requests that contain user information. All allows you to provide more criteria to distinguish the user information requests from all the rest.
(+) and (-) The plus and minus buttons add and remove criteria. Clicking the () button allows you to add a new branch of logic with its own All/Any operator.

API Call Criteria
Endpoint Criteria Dropdown
Endpoint Criteria Dropdown
  • hostname: The domain name of your server
  • method: The HTTP method of the request
  • Page hostname: This filters on the hostname of the user’s location.
  • path: The part of the URL after the domain name
  • url: The entire URL of the response, including protocol, domain name and path
  • Page url: This filters on the url of the user’s location.
  • status: The HTTP status code of the response
  • responseJSON: This allows you to specify a particular JSON structure in the server’s response. If that structure is not present in the response, this criteria will not match. For example, a rule like responseJSON : name.first : is : David would match when the JSON has the structure:

    {
      ...,
      "name": {
        ...,
        "first": "David",
        ...,
      },
      ...,
    }
    

For a complete list of filter criteria available in Hawk, see here.

API Call Comparators
Endpoint Comparator Dropdown

(Note: Not all comparators are valid for all filter criteria.)

  • Is: Matches when the specified string and the result are identical.
  • Is Not: Matches when the specified string and the result are different.
  • Starts With: Matches when the specified string appears at the beginning of the result.
  • End With: Matches when the specified string appears at the end of the result.
  • Matches: Allows you to enter a regular expression. Matches if the regular expression matches.
  • Does Not Match: Allows you to enter a regular expression. Matches if the regular expression does not match.
  • GT: Greater than. Only used for numbers.
  • LT: Less than. Only used for numbers.
  • Between: Allows you to supply two numbers. Matches when the result is between them.
  • Field.Name: Only used for the resoponseJSON criterion. This specifies a location within the response JSON to match.
  • Is Truthy: Matches when the result is truthy.
  • Is Falsy: Matches when the result is falsy.

Did you find this article helpful?