Custom Attributes

Overview

Custom Attributes in iOS enable developers to store and use user-specific information such as preferences, demographics, or activity data. These attributes enhance user engagement by allowing targeted and personalized communication.

Use Case

1. Purpose:

   • Store user-specific data for personalized engagement.

   • Create user segments for tailored campaigns.

2. Benefits:

   • Improve user satisfaction with relevant content and offers.

   • Facilitate data-driven insights for marketing and analytics.

Implementation Details

Warning:

The bulk-set selector exported by the SDK is setCustomAttributtes:withCompletionHandler: — the public header has a typo (Attributtes with a double t). Use the symbol exactly as shown; otherwise the call will not link. The matching getter getCustomAttributes:withCompletionHandler: is spelled correctly.

1. Set Individual Custom Attributes: Assign user-specific values such as strings, numbers, or dates. Each setter takes an AppoxeeCompletionHandler block of type ^(NSError * _Nullable error, id _Nullable data).

   Swift

   Objective-C

   Appoxee.shared()?.setStringValue("JohnDoe", forKey: "userName") { error, data in
       if error == nil { print("String attribute set successfully.") }
   }
   
   Appoxee.shared()?.setNumberValue(150, forKey: "userScore") { error, data in
       if error == nil { print("Numeric attribute set successfully.") }
   }
   
   Appoxee.shared()?.setDateValue(Date(), forKey: "userBirthday") { error, data in
       if error == nil { print("Date attribute set successfully.") }
   }

   // String value
   [[Appoxee shared] setStringValue:@"JohnDoe"
                             forKey:@"userName"
              withCompletionHandler:^(NSError * _Nullable error, id _Nullable data) {
       if (!error) {
           NSLog(@"String attribute set successfully.");
       }
   }];
   
   // Numeric value
   [[Appoxee shared] setNumberValue:@150
                             forKey:@"userScore"
              withCompletionHandler:^(NSError * _Nullable error, id _Nullable data) {
       if (!error) {
           NSLog(@"Numeric attribute set successfully.");
       }
   }];
   
   // Date value
   [[Appoxee shared] setDateValue:[NSDate date]
                           forKey:@"userBirthday"
            withCompletionHandler:^(NSError * _Nullable error, id _Nullable data) {
       if (!error) {
           NSLog(@"Date attribute set successfully.");
       }
   }];

2. Set Multiple Custom Attributes at Once: Use the bulk-set selector to send several key/value pairs in a single call.

   Swift

   Objective-C

   Appoxee.shared()?.setCustomAttributtes([
       "userName": "JohnDoe",
       "userScore": 150,
       "userBirthday": Date()
   ]) { error, data in
       if error == nil {
           print("Custom attributes updated successfully (bulk).")
       }
   }

   [[Appoxee shared] setCustomAttributtes:@{
       @"userName": @"JohnDoe",
       @"userScore": @150,
       @"userBirthday": [NSDate date]
   } withCompletionHandler:^(NSError * _Nullable error, id _Nullable data) {
       if (!error) {
           NSLog(@"Custom attributes updated successfully (bulk).");
       }
   }];

3. Retrieve Custom Attributes: Fetch a single attribute by key, or fetch all stored attributes at once.

   Swift

   Objective-C

   Appoxee.shared()?.fetchCustomField(byKey: "userName") { error, data in
       if error == nil {
           print("Fetched Attribute: \(data ?? "None")")
       }
   }
   
   Appoxee.shared()?.getCustomAttributes(nil) { error, data in
       if error == nil, let attributes = data as? [String: Any] {
           print("All attributes: \(attributes)")
       }
   }

   // Fetch a single attribute by key
   [[Appoxee shared] fetchCustomFieldByKey:@"userName"
                     withCompletionHandler:^(NSError * _Nullable error, id _Nullable data) {
       if (!error) {
           NSLog(@"Fetched Attribute: %@", data);
       }
   }];
   
   // Fetch all custom attributes
   [[Appoxee shared] getCustomAttributes:nil
                   withCompletionHandler:^(NSError * _Nullable error, id _Nullable data) {
       if (!error) {
           NSDictionary *attributes = (NSDictionary *)data;
           NSLog(@"All attributes: %@", attributes);
       }
   }];

4. Increment Numeric Attributes: Update numeric values dynamically.

   Appoxee.shared()?.incrementNumericKey("userScore", byNumericValue: 10) { error, data in
       if error == nil {
           print("Numeric attribute incremented successfully.")
       }
   }

Parameter Behaviour

• key — The attribute name. Use stable keys that are consistent across platforms.

• value — The attribute value (string, number, or date depending on the setter).

• attributes — Dictionary of attribute key/value pairs to set in one call (bulk setter).

• withCompletionHandler — AppoxeeCompletionHandler block of type ^(NSError * _Nullable error, id _Nullable data). Inspect error for failure; data carries response payload (for example, the requested attribute value for getters) and may be nil for setters.

Keep in mind:

• Custom attributes can be used as targeting criteria for dynamic and personalized push messages.

• Use keys that are consistent across iOS, Android, and Web for uniform data handling.

• Test attribute setters and getters under different app states (foreground, background, terminated) for accuracy.

• To re-sync all locally stored attributes with the backend after setting a new alias, see Set User Identifier and the withResendAttributes parameter.