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.

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

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

Set Multiple Custom Attributes at Once

Use the bulk-set selector to send several key/value pairs in a single call.

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

Retrieve Custom Attributes

Fetch a single attribute by key, or fetch all stored attributes at once.

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

Increment Numeric Attributes

Update numeric values dynamically. The byNumericValue parameter takes an NSNumber — pass any integer or floating-point literal in Swift, or use the @(...) boxing syntax in Objective-C.

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

[[Appoxee shared] incrementNumericKey:@"userScore"
                        byNumericValue:@10
                 withCompletionHandler:^(NSError * _Nullable error, id _Nullable data) {
    if (!error) {
        NSLog(@"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.