Advanced targeting with custom properties

Advanced targeting demo video

If you just want to see this in action, watch this video:

Introduction

Custom properties allow you to target specific users using parameters that you decide.

Difficulty level: medium - requires some JavaScript coding

Hopefully this documentation is helpful to you! If there's anything you feel is missing, or if you run into any issues along the way, simply reach out to us at hey@hopscotch.club

You will need to have the Hopscotch script installed before you can use custom properties. Simply follow the instructions in the app settings page.

Once installed, you can send custom properties to identify your users with the identify function. This function accepts a JavaScript object with any key/value pairs. Here is a basic example:

// Example Hopscotch identify call with a variety of types.

window.Hopscotch('identify', {
  email: 'michael.scott@dundermifflin.com',
  sign_up_date: '2021-06-23T15:05:36.755Z',
  is_trial_user: true,
  total_number_sessions: 5,
});

Accepted types

Hopscotch accepts four different types of custom properties:

• text (ex: email, first name, last name) ⚠️ Note: text fields are case sensitive. "Michael" will not match "michael"

  jsx window.Hopscotch('identify', { email: "michael.scott@dundermifflin.com", first_name: "Michael", // ... rest of your fields })

• date (ex: sign up date, trial expiry date).

  Must be sent in ISO string format. See code example for details.

  window.Hopscotch('identify', {
    // A date that is already in ISO format.
    sign_up_date: '2021-06-23T15:05:36.755Z',
  
    // This is how you can convert an existing date to ISO format
    trial_expiry_date: new Date('July 5, 2005').toISOString(),
  
    // This is how you can format the current date to ISO format.
    current_date: new Date().toISOString(),
  
    // ... rest of your fields
  });
  

• boolean (also known as true/false)

  window.Hopscotch('identify', {
    is_trial_user: true,
    has_paid: false,
    // ... rest of your fields
  });
  

• number

  window.Hopscotch('identify', {
    number_of_sessions: 5,
    account_id: 513546214,
    // ... rest of your fields
  });
  

Ignored types

It is important to note that Hopscotch only supports the types mentioned above. All other values will be ignored.

The following types will be ignored:

• arrays
• nested objects
• undefined or null values

Example of changing ignored types to accepted types

// ⛔️ The following call won't work. The array and nested values will be ignored.

window.Hopscotch('identify', {
  sessions: [1, 2, 3, 4],
  user: {
    first_name: 'Michael',
    last_name: 'Scott',
    plan: {
      name: 'free',
    },
  },
});

// ✅ Instead you can restructure the above call as it is shown below.
// Notice how we have flattened the shape to remove any nested fields.

window.Hopscotch('identify', {
  total_sessions: [1, 2, 3, 4].length, // this will convert to a number
  user_first_name: 'Michael',
  user_last_name: 'Scott',
  user_plan_name: 'free',
});

Gotchas with types

Always send the same type for a specific property

If you send the same field in subsequent calls, but one was a boolean and the next was a date, Hopscotch will assume the latest value received (in this case: date).

If you expect to send one property as multiple types, you should separate this property into two distinct fields before sending to Hopscotch.

How it works

We do not store the values on our server. We keep them in the browser's localStorage.

Use custom properties to target specific users

This video below shows you how to use custom properties from your identify calls to do advanced targeting.