Guides
Log InSign Up

External User IDs

Add your custom User IDs within OneSignal.

Suggest Edits

OneSignal's External User ID is a string data type property you can set to associate your own User IDs to each of their corresponding OneSignal device records.

Users can have multiple subscriptions.

Users can have multiple subscriptions.

📘

Benefits of External User ID

The benefits of External User Id include the ability to:

  1. Target devices with push and email through our Create Notification REST API Call using the include_external_user_ids targeting parameter. Also see Sending Transactional Messages.
  2. Use the CSV List Upload feature to tag and segment users based on the external_user_id's set in our system.
  3. Update tags with our API Edit Tags with External User Id endpoint.
  4. Leverage our integrations with HubSpot, Mixpanel, Amplitude, and Segment.com which leverage External User Id to sync cohorts / user properties

OneSignal creates and stores device & channel level data under a unique subscription ID called the Player ID. A single user can have multiple Player ID records based on how many devices, email addresses, and phone numbers they use to interact with your app/site.

For example, a user:

  1. downloads your app on Android, gets a unique Android Push Player ID record.
  2. subscribes to your website, a new Player ID is created for the web push record.
  3. downloads your app on iOS, gets a unique iOS Push Player ID record.
  4. provides you their Email Address, which creates an Email channel record Player ID.
  5. provides their Phone Number, which creates an SMS channel record Player ID.

This is 5 Player ID records in OneSignal for the 1 User.

You can send OneSignal your unique User ID called the External User ID to associate multiple Player ID records.

Linking an External User ID to the OneSignal Player ID

The External User ID can be set with the following options:

  1. Client-side SDK (recommended) setExternalUserId method.
  2. Server-side API Edit device endpoint.
  3. Dashboard CSV User Attributes Importer.

setExternalUserId Method

The OneSignal SDK setExternalUserId method should be called when the user logs into the app/site and within the callback of the setEmail and setSMSNumber methods to link the records together.

let externalUserId = "123456789"; // You will supply the external user id to the OneSignal SDK

OneSignal.push(function() {
  OneSignal.setExternalUserId(externalUserId);
});

String externalUserId = "123456789"; // You will supply the external user id to the OneSignal SDK

// Setting External User Id with Callback Available in SDK Version 4.0.0+
OneSignal.setExternalUserId(externalUserId, new OneSignal.OSExternalUserIdUpdateCompletionHandler() {
    @Override
    public void onSuccess(JSONObject results) {
        try {
            if (results.has("push") && results.getJSONObject("push").has("success")) {
                boolean isPushSuccess = results.getJSONObject("push").getBoolean("success");
                OneSignal.onesignalLog(OneSignal.LOG_LEVEL.VERBOSE, "Set external user id for push status: " + isPushSuccess);
            }
        } catch (JSONException e) {
            e.printStackTrace();
        }

        try {
            if (results.has("email") && results.getJSONObject("email").has("success")) {
                boolean isEmailSuccess = results.getJSONObject("email").getBoolean("success");
                OneSignal.onesignalLog(OneSignal.LOG_LEVEL.VERBOSE, "Set external user id for email status: " + isEmailSuccess);
            }
        } catch (JSONException e) {
            e.printStackTrace();
        }
        try {
            if (results.has("sms") && results.getJSONObject("sms").has("success")) {
                boolean isSmsSuccess = results.getJSONObject("sms").getBoolean("success");
                OneSignal.onesignalLog(OneSignal.LOG_LEVEL.VERBOSE, "Set external user id for sms status: " + isSmsSuccess);
            }
        } catch (JSONException e) {
            e.printStackTrace();
        }
    }

    @Override
    public void onFailure(OneSignal.ExternalIdError error) {
        // The results will contain channel failure statuses
        // Use this to detect if external_user_id was not set and retry when a better network connection is made
        OneSignal.onesignalLog(OneSignal.LOG_LEVEL.VERBOSE, "Set external user id done with error: " + error.toString());
    }
});

let externalUserId = "123456789" // You will supply the external user id to the OneSignal SDK

// Setting External User Id with Callback Available in SDK Version 3.0.0+
OneSignal.setExternalUserId(externalUserId, withSuccess: { results in
    // The results will contain push and email success statuses
    print("External user id update complete with results: ", results!.description)
    // Push can be expected in almost every situation with a success status, but
    // as a pre-caution its good to verify it exists
    if let pushResults = results!["push"] {
        print("Set external user id push status: ", pushResults)
    }
    if let emailResults = results!["email"] {
        print("Set external user id email status: ", emailResults)
    }
    if let smsResults = results!["sms"] {
        print("Set external user id sms status: ", smsResults)
    }
}, withFailure: {error in
    print("Set external user id done with error: " + error.debugDescription)
})

NSString* externalUserId = @"123456789"; // You will supply the external user id to the OneSignal SDK

// Setting External User Id with Callback Available in SDK Version 3.0.0+
[OneSignal setExternalUserId:externalUserId withSuccess:^(NSDictionary *results) {
    // The results will contain push and email success statuses
    NSLog(@"External user id update complete with results: %@", results.description);
    // Push can be expected in almost every situation with a success status, but
    // as a pre-caution its good to verify it exists
    if (results[@"push"] && results[@"push"][@"success"])
      NSLog(@"Set external user id push status: %@", results[@"push"][@"success"]);
    // Verify the email is set or check that the results have an email success status
    if (results[@"email"] && results[@"email"][@"success"])
      NSLog(@"Set external user id email status: %@", results[@"email"][@"success"]);
    // Verify the number is set or check that the results have an sms success status
    if (results[@"sms"] && results[@"sms"][@"success"])
      NSLog(@"Set external user id sms status: %@", results[@"sms"][@"success"]);
} withFailure:^(NSError *error) {
      NSLog(@"External user id update failed with error: %@", error);
}];

OneSignal.Default.SetExternalUserId("123456789");
// or
var result = await OneSignal.Default.SetExternalUserId("123456789");
if (result) {
    Debug.Log("success");
}

let externalUserId = '123456789'; // You will supply the external user id to the OneSignal SDK

// Setting External User Id with Callback Available in SDK Version 3.9.3+
OneSignal.setExternalUserId(externalUserId, (results) => {
  // The results will contain push and email success statuses
  console.log('Results of setting external user id');
  console.log(results);
  
  // Push can be expected in almost every situation with a success status, but
  // as a pre-caution its good to verify it exists
  if (results.push && results.push.success) {
    console.log('Results of setting external user id push status:');
    console.log(results.push.success);
  }
  
  // Verify the email is set or check that the results have an email success status
  if (results.email && results.email.success) {
    console.log('Results of setting external user id email status:');
    console.log(results.email.success);
  }

  // Verify the number is set or check that the results have an sms success status
  if (results.sms && results.sms.success) {
    console.log('Results of setting external user id sms status:');
    console.log(results.sms.success);
  }
});

let externalUserId = '123456789'; // You will supply the external user id to the OneSignal SDK

// Setting External User Id with Callback Available in SDK Version 3.9.3+
OneSignal.shared.setExternalUserId(externalUserId).then((results) {
  log(results.toString());
}).catchError((error) {
  log(error.toString());
});

let externalUserId = '123456789'; // You will supply the external user id to the OneSignal SDK

// Setting External User Id with Callback Available in SDK Version 2.11.2+
window.plugins.OneSignal.setExternalUserId(externalUserId, (results) => {
  // The results will contain push and email success statuses
  console.log('Results of setting external user id');
  console.log(results);
  
  // Push can be expected in almost every situation with a success status, but
  // as a pre-caution its good to verify it exists
  if (results.push && results.push.success) {
    console.log('Results of setting external user id push status:');
    console.log(results.push.success);
  }
  
  // Verify the email is set or check that the results have an email success status
  if (results.email && results.email.success) {
    console.log('Results of setting external user id email status:');
    console.log(results.email.success);
  }

  // Verify the number is set or check that the results have an sms success status
  if (results.sms && results.sms.success) {
    console.log('Results of setting external user id sms status:');
    console.log(results.sms.success);
  }
});

string externalUserId = "123456789"; // You will supply the external user id to the OneSignal SDK

// Setting External User Id with Callback Available in SDK Version 3.8.0+
OneSignal.Current.SetExternalUserId(externalId);

//Callback available in SDK Version 3.8.0+
private static void OneSignalSetExternalUserId(Dictionary<string, object> results)
{
  // The results will contain push and email success statuses
  Debug.WriteLine("External user id updated with results: " + Json.Serialize(results));
  // Push can be expected in almost every situation with a success status, but
  // as a pre-caution its good to verify it exists
  if (results.ContainsKey("push"))
  {
    Dictionary<string, object> pushStatusDict = results["push"] as Dictionary<string, object>;
    if (pushStatusDict.ContainsKey("success"))
    {
      Debug.WriteLine("External user id updated for push with results: " + pushStatusDict["success"] as string);
    }
  }
  // Verify the email is set or check that the results have an email success status
  if (results.ContainsKey("email"))
  {
    Dictionary<string, object> emailStatusDict = results["email"] as Dictionary<string, object>;
    if (emailStatusDict.ContainsKey("success"))
    {
      Debug.WriteLine("External user id updated for email with results: " + emailStatusDict["success"] as string);
    }
  }
}

If you have a backend server, we strongly recommend using Identity Verification with your users. Your backend can generate an identifier authentication token and send it to your site.

🚧

Warning - Android SDK Data Synchronization

The OneSignal Android SDKs leverage cacheing on External User ID and Data Tags.

If setting External User ID through the Edit device API Endpoint, then use the same endpoint to remove the External User ID upon the user logging out of the app.

The removeExternalUserId method will not work unless the External User ID is set first with the setExternalUserId method on Android.

This is only applicable on the OneSignal Android Mobile App SDKs.

Disassociating the External User ID

External User IDs can be disassociated from the current device's Player ID record using the OneSignal SDK removeExternalUserId method.

removeExternalUserId Method

It is recommended to call this method when the user logs out of your app. 

OneSignal.push(function() {
  OneSignal.removeExternalUserId();
});

// Removing External User Id with Callback Available in SDK Version 3.13.0+
OneSignal.removeExternalUserId(new OneSignal.OSExternalUserIdUpdateCompletionHandler() {
  @Override
    public void onComplete(JSONObject results) {
    // The results will contain push and email success statuses
    OneSignal.onesignalLog(OneSignal.LOG_LEVEL.VERBOSE, "Remove external user id done with results: " + results.toString());
    
    // Push can be expected in almost every situation with a success status, but
    // as a pre-caution its good to verify it exists
    if (results.has("push") && results.getJSONObject("push").has("success")) {
      boolean isPushSuccess = results.getJSONObject("push").getBoolean("success");
      OneSignal.onesignalLog(OneSignal.LOG_LEVEL.VERBOSE, "Remove external user id for push status: " + isPushSuccess);
    }
    
    // Verify the email is set or check that the results have an email success status
    if (results.has("email") && results.getJSONObject("email").has("success")) {
      boolean isEmailSuccess = results.getJSONObject("email").getBoolean("success");
      OneSignal.onesignalLog(OneSignal.LOG_LEVEL.VERBOSE, "Remove external user id for email status: " + isEmailSuccess);
    }
  }
});

// Removing External User Id with Callback Available in SDK Version 2.13.1+
OneSignal.removeExternalUserId({ results in
    // The results will contain push and email success statuses
    print("External user id update complete with results: ", results!.description)
    // Push can be expected in almost every situation with a success status, but
    // as a pre-caution its good to verify it exists
    if let pushResults = results!["push"] {
        print("Remove external user id push status: ", pushResults)
    }
    // Verify the email is set or check that the results have an email success status
    if let emailResults = results!["email"] {
        print("Remove external user id email status: ", emailResults)
    }
})

// Removing External User Id with Callback Available in SDK Version 2.13.0+
[OneSignal removeExternalUserId:^(NSDictionary *results) {
  // The results will contain push and email success statuses
  NSLog(@"External user id update complete with results: %@", results.description);
  
  // Push can be expected in almost every situation with a success status, but
  // as a pre-caution its good to verify it exists
  if (results["push"] && results["push"]["success"])
    NSLog(@"Remove external user id push status: %@", results["push"]["success"]);
  
  // Verify the email is set or check that the results have an email success status
  if (results["email"] && results["email"]["success"])
    NSLog(@"Remove external user id email status: %@", results["email"]["success"]);
}];

OneSignal.Default.RemoveExternalUserId();
// or
var result = await OneSignal.Default.RemoveExternalUserId();
if (result){
    Debug.Log("success");
}

// Remove External User Id with Callback Available in SDK Version 3.7.0+
OneSignal.removeExternalUserId((results) => {
  // The results will contain push and email success statuses
  console.log('Results of removing external user id');
  console.log(results);
  // Push can be expected in almost every situation with a success status, but
  // as a pre-caution its good to verify it exists
  if (results.push && results.push.success) {
    console.log('Results of removing external user id push status:');
    console.log(results.push.success);
  }
  
  // Verify the email is set or check that the results have an email success status
  if (results.email && results.email.success) {
    console.log('Results of removoing external user id email status:');
    console.log(results.email.success);
  }
});

//Available in SDK Version 3.6.5-
//OneSignal.removeExternalUserId()

//usually called after the user logs out of your app
OneSignal.shared.removeExternalUserId()

// Remove External User Id with Callback Available in SDK Version 2.9.0+
window.plugins.OneSignal.removeExternalUserId((results) => {
  // The results will contain push and email success statuses
  console.log('Results of removing external user id');
  console.log(results);
  // Push can be expected in almost every situation with a success status, but
  // as a pre-caution its good to verify it exists
  if (results.push && results.push.success) {
    console.log('Results of removing external user id push status:');
    console.log(results.push.success);
  }
  
  // Verify the email is set or check that the results have an email success status
  if (results.email && results.email.success) {
    console.log('Results of removoing external user id email status:');
    console.log(results.email.success);
  }
});

//Available in SDK Version 2.8.4-
//window.plugins.OneSignal.removeExternalUserId();

// Removing External User Id with Callback Available in SDK Version 3.8.0+
OneSignal.Current.RemoveExternalUserId(OneSignalSetExternalUserId);

//See setExternalUserId method for callback Available in SDK Version 3.8.0+

Retrieving External User Id

getExternalUserId Method

Web only - Gets the value stored locally on the user's browser.

OneSignal.push(function() {
  OneSignal.getExternalUserId().then(function(externalUserId){
    console.log("externalUserId: ", externalUserId);
  });
});

Updated over 1 year ago

What’s Next