Set User Identifier

Overview

The Set User Identifier feature in iOS allows developers to assign a unique identifier (alias) to the device's user. This identifier helps maintain consistent user profiles, enables personalized communication, and supports user segmentation.

Use Case

1. Purpose:

   • Link user-specific data, such as preferences or behaviours, across devices.

   • Enable targeted marketing campaigns and personalized notifications.

2. Benefits:

   • Improve user segmentation and targeting accuracy.

   • Provide a seamless and personalized user experience.

Implementation Details

Assign or Update a User Identifier

Use setDeviceAlias:withCompletionHandler: for the simple case, or setDeviceAlias:withResendAttributes:withCompletionHandler: when you need to control whether previously set custom attributes are re-sent to the backend together with the alias change.

// Set alias only
Appoxee.shared()?.setDeviceAlias("user12345") { error, data in
    if error == nil {
        print("User Identifier set successfully.")
    } else {
        print("Failed to set User Identifier: \(error?.localizedDescription ?? "Unknown error")")
    }
}

// Set alias and re-sync all previously set custom attributes
Appoxee.shared()?.setDeviceAlias("user12345", withResendAttributes: true) { error, data in
    if error == nil {
        print("User Identifier set successfully (attributes re-sent).")
    }
}

// Set alias without re-sending previously set custom attributes
Appoxee.shared()?.setDeviceAlias("user12345", withResendAttributes: false) { error, data in
    if error == nil {
        print("User Identifier set successfully (no attribute re-send).")
    }
}

// Set alias only
[[Appoxee shared] setDeviceAlias:@"user12345"
          withCompletionHandler:^(NSError * _Nullable error, id _Nullable data) {
    if (!error) {
        NSLog(@"User Identifier set successfully.");
    } else {
        NSLog(@"Failed to set User Identifier: %@", error.localizedDescription);
    }
}];

// Set alias and re-sync all previously set custom attributes
[[Appoxee shared] setDeviceAlias:@"user12345"
          withResendAttributes:YES
          withCompletionHandler:^(NSError * _Nullable error, id _Nullable data) {
    if (!error) {
        NSLog(@"User Identifier set successfully (attributes re-sent).");
    }
}];

// Set alias without re-sending previously set custom attributes
[[Appoxee shared] setDeviceAlias:@"user12345"
          withResendAttributes:NO
          withCompletionHandler:^(NSError * _Nullable error, id _Nullable data) {
    if (!error) {
        NSLog(@"User Identifier set successfully (no attribute re-send).");
    }
}];

Parameter behaviour

• alias — The unique identifier for the user.

• withResendAttributes — When YES/true, the SDK re-sends all previously set custom attributes for this device to ensure backend state is fully aligned (useful after data loss, migrations, or cross-device reconciliation). When NO/false, only the alias change is sent, avoiding additional network and processing overhead.

• withCompletionHandler — AppoxeeCompletionHandler block of type ^(NSError * _Nullable error, id _Nullable data). Inspect error to determine success; data is reserved for additional response payload and may be nil.

Retrieve the User Identifier

Fetch the currently assigned alias. The returned data object is the alias string.

Appoxee.shared()?.getDeviceAlias { error, data in
    if error == nil, let alias = data as? String {
        print("Retrieved User Identifier: \(alias)")
    } else {
        print("Failed to retrieve User Identifier: \(error?.localizedDescription ?? "Unknown error")")
    }
}

[[Appoxee shared] getDeviceAliasWithCompletionHandler:^(NSError * _Nullable error, id _Nullable data) {
    if (!error) {
        NSString *alias = (NSString *)data;
        NSLog(@"Retrieved User Identifier: %@", alias);
    } else {
        NSLog(@"Failed to retrieve User Identifier: %@", error.localizedDescription);
    }
}];

Remove the User Identifier

To disassociate the alias from the device, use logoutWithOptin:. The SDK clears the user-to-device association as part of the logout flow. The optin flag controls whether the device remains subscribed to push after the user is removed — see Logout Device for details and tenant-side considerations.

Appoxee.shared()?.logout(withOptin: true)

[[Appoxee shared] logoutWithOptin:YES];

Warning:

The legacy method removeDeviceAliasWithCompletionHandler: is deprecated in the public header. Use logoutWithOptin: instead.

Best Practices

• Use Unique Identifiers: Ensure the identifier is unique for each user to avoid conflicts across devices.

• Error Handling: Inspect the error argument of every completion block to ensure reliable operation under varying network conditions.

• Privacy Compliance: Ensure that user identifiers comply with privacy regulations (e.g., GDPR) and are managed securely.

Keep in mind:

• User identifiers are device-specific but can be used to associate multiple devices with the same user profile.

• Use meaningful identifiers like  addresses, usernames, or system-generated IDs for clarity and management.

• Test all identifier operations (set, retrieve, and remove) under different app states (foreground, background, and terminated) for reliability.