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

1. 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.

   Swift

   Objective-C

   // 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.

2. Retrieve the User Identifier: Fetch the currently assigned alias. The returned data object is the alias string.

   Swift

   Objective-C

   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);
       }
   }];

3. 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.

   Swift

   Objective-C

   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.