Identify a Subscriber

The RH.identify function is used to identify a subscriber so that they don’t need to manually enter their information again, such as their email address or name. This function is particularly useful for displaying embeddable widgets on internal pages of your website where you already have the subscriber’s unique identifier.

RH_MFxxxxxxxxxx.identify(data, force, callback);

Note: The RH.identify function is an advanced version of the 'Add a Subscriber' function and offers additional properties like upsert, force identification, and more. It is not always necessary to call RH.identify if you have already used an 'Add a Subscriber' function, as 'Add a Subscriber' will also identify the subscriber.

Parameters

1. Data (Object, Required): An object containing user data. At a minimum, this object must include the unique identifier of the user. Additional fields can be included as needed.

2. Force (Boolean, Optional): Determines whether to override an existing session. The default value is false. Set this to true to force identification even if the user is already identified.

3. Callback (Function, Optional): A callback function that is executed if the identification succeeds. This function receives the subscriber data as a parameter.

var myFunc = function(data) {
   console.log(data);
}

var data = {
  email: "[e-mail]",
  name: "John Smith",
  extra_field: "USA",
  extra_field_2: null,
  upsert: true
}

RH_MFxxxxxxxxxx.identify(data, false, myFunc);

Important: Replace 'MFxxxxxxxxxx' with your actual campaign UUID.

Implementation Example

Here’s how you might use the RH.identify function with a form submission:

JavaScript

<script type="text/javascript">
    window.RHConfig = {
      callbacks: {
        ready: function() {
          var form = document.getElementById('form');
            form.addEventListener("submit", function(e){

              var data = {
                email: form.querySelector('#email').value,
                name: form.querySelector('#name').value,
                upsert : true
              };
              
              var myCallback = function(responseData) {
                console.log("Identification successful:", responseData);
              };

              if (RH_MFxxxxxxxxxx) {
                RH_MFxxxxxxxxxx.identify(data, false, myCallback);
              }
            });
          }
        }
      };

</script>

Detailed Behavior

1. Automatic Subscriber Creation: When the RH.identify function is called, ReferralHero will check if a subscriber with that specific unique identifier exists.

   • If a subscriber is not found, a new subscriber is automatically created using the data sent over, bypassing the verification method.

   • If the subscriber with that unique identifier already exists, ReferralHero simply returns the existing subscriber data.

   If you don’t want to automatically create a new subscriber when one isn't found (e.g., to allow manual opt-in), set the upsert property to false.

2. Load Callback: The ReferralHero Tracking Code loads asynchronously. If you intend to execute any RH functions on page load, you must wait until the library has completely loaded. Use the callbacks.ready method to ensure that the code runs only after ReferralHero has finished loading.

3. Force Identification: By default, if a cookie session is already present (e.g., the user has already been identified in the past), ReferralHero will not attempt to identify the user again to improve the user experience. This avoids unnecessary delays (typically around 1 second).

   If you want to identify users every time regardless of an existing session, set the force parameter to true.

Note: Our recommendation is to not force identification, as it can degrade the user experience. If you force identification, ReferralHero will check the existence of the subscriber every time a person visits that page, which can slow down your website.

Important

• If you have already called the RH.form.submit() function on a portal signup/login form, there is no need to call RH.identify() again on an internal page as the subscriber is already identified.

• The upsert property allows you to update an existing subscriber's information or create a new subscriber if one does not exist. Setting upsert to false prevents the automatic creation of a new subscriber.

• The force parameter can be used to override an existing session and re-identify the user if needed. However, avoid using it to prevent impacting user experience.

• The callback parameter allows you to execute custom code upon successful identification, making it easier to handle responses or perform additional actions.

ReCaptcha

Unfortunately, if you're using ReCaptcha, RH_MFxxxxxxxxxx.identify() will not work.