Guides
Log InSign Up

External User ID (legacy)

This is a deprecated page!

Suggest Edits

❗️

Method Deprecation Warning

If you've found yourself on this page, please check out the following documentation pages:

What was deprecated?

The setExternalUserId method will be deprecated in version 5+ of our SDKs.

Instead, the External User ID will now be called External ID and will be used as the default alias for the new OneSignal.login method.

See the User Model Migration Guide for more details.

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.

Disassociating the External User Id

External User Ids can be disassociated from the current device's subscription_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+

Updated 10 months ago

What’s Next