Set User Identifier

Overview

The Set User Identifier feature in iOS allows developers to assign a unique identifier to users across devices. This identifier helps maintain consistent user profiles, enable personalized communication, and segment users.

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 (with optional resend): Use the SDK method to set a unique identifier for a user. You can choose whether to re-sync all previously set custom attributes with the backend by using the resendAttributes parameter.

   For Objective-C:

   // Set alias and re-sync all custom attributes to the backend
   [[Appoxee shared] setDeviceAlias:@"user12345"
                 resendAttributes:YES
           withCompletionHandler:^(NSError * _Nullable error) {
       if (!error) {
           NSLog(@"User Identifier set successfully (attributes re-sent).");
       } else {
           NSLog(@"Failed to set User Identifier: %@", error.localizedDescription);
       }
   }];
   // Set alias without re-sending previously set custom attributes
   [[Appoxee shared] setDeviceAlias:@"user12345"
                 resendAttributes:NO
           withCompletionHandler:^(NSError * _Nullable error) {
       if (!error) {
           NSLog(@"User Identifier set successfully (no attribute re-send).");
       } else {
           NSLog(@"Failed to set User Identifier: %@", error.localizedDescription);
       }
   }];

   For Swift:

   // Set alias and re-sync all custom attributes to the backend
   Appoxee.shared()?.setDeviceAlias("user12345", resendAttributes: true) { error in
       if error == nil {
           print("User Identifier set successfully (attributes re-sent).")
       } else {
           print("Failed to set User Identifier: \(error?.localizedDescription ?? "Unknown error")")
       }
   }
   // Set alias without re-sending previously set custom attributes
   Appoxee.shared()?.setDeviceAlias("user12345", resendAttributes: false) { error in
       if error == nil {
           print("User Identifier set successfully (no attribute re-send).")
       } else {
           print("Failed to set User Identifier: \(error?.localizedDescription ?? "Unknown error")")
       }
   }

   Parameter behaviour

   • alias — The unique identifier for the user.

   • resendAttributes — When 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 false, only the alias change is sent, avoiding additional network and processing overhead.

   • completionHandler — Invoked with an NSError if the operation fails.

2. Retrieve the User Identifier: Fetch the currently assigned user identifier.

   For Objective-C:

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

   For Swift:

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

3. Remove the User Identifier: Disassociate the user identifier from the device.

   For Objective-C:

   [[Appoxee shared] removeDeviceAliasWithCompletionHandler:^(NSError * _Nullable error) {
       if (!error) {
           NSLog(@"User Identifier removed successfully.");
       } else {
           NSLog(@"Failed to remove User Identifier: %@", error.localizedDescription);
       }
   }];

   For Swift:

   Appoxee.shared()?.removeDeviceAliasWithCompletionHandler { error in
       if error == nil {
           print("User Identifier removed successfully.")
       } else {
           print("Failed to remove User Identifier: \(error?.localizedDescription ?? "Unknown error")")
       }
   }

Best Practices

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

• Error Handling: Implement robust error handling for all API calls to ensure reliable operation in various 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 to the same user profile.

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

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