Tags

Overview

Tags help categorize devices and users for segmentation and targeted messaging. The Mapp Engage iOS SDK exposes two distinct tag scopes:

• Device tags — tags assigned to the current device. Use these to segment users.

• Application tags — the whitelist of tag names defined for the application as a whole. Use this to discover which tag names are valid before assigning them.

Use Case

1. Purpose:

   • Label devices with specific attributes (for example, "NewsletterSubscriber", "GamingEnthusiast").

   • Drive dynamic segmentation for personalized notifications.

2. Benefits:

   • Improved targeting for push and inbox messages.

   • Simpler user management and reporting.

Implementation Details

All tag completion handlers use the standard AppoxeeCompletionHandler signature: ^(NSError * _Nullable error, id _Nullable data).

1. Add tags to the device:

   Swift

   Objective-C

   Appoxee.shared()?.addTags(toDevice: ["NewsletterSubscriber", "FrequentBuyer"]) { error, data in
       if error == nil { print("Tags added.") }
   }

   [[Appoxee shared] addTagsToDevice:@[@"NewsletterSubscriber", @"FrequentBuyer"]
               withCompletionHandler:^(NSError * _Nullable error, id _Nullable data) {
       if (!error) {
           NSLog(@"Tags added.");
       }
   }];

2. Remove tags from the device:

   Swift

   Objective-C

   Appoxee.shared()?.removeTags(fromDevice: ["NewsletterSubscriber"]) { error, data in
       if error == nil { print("Tags removed.") }
   }

   [[Appoxee shared] removeTagsFromDevice:@[@"NewsletterSubscriber"]
                    withCompletionHandler:^(NSError * _Nullable error, id _Nullable data) {
       if (!error) {
           NSLog(@"Tags removed.");
       }
   }];

3. Add and remove tags in a single call:

   Swift

   Objective-C

   Appoxee.shared()?.addTags(toDevice: ["VIP"], andRemove: ["Trial"]) { error, data in
       if error == nil { print("Tags updated atomically.") }
   }

   [[Appoxee shared] addTagsToDevice:@[@"VIP"]
                            andRemove:@[@"Trial"]
               withCompletionHandler:^(NSError * _Nullable error, id _Nullable data) {
       if (!error) {
           NSLog(@"Tags updated atomically.");
       }
   }];

4. Fetch device tags: Returns the tags currently assigned to this device.

   Swift

   Objective-C

   Appoxee.shared()?.fetchDeviceTags { error, data in
       if error == nil, let tags = data as? [String] {
           print("Device tags: \(tags)")
       }
   }

   [[Appoxee shared] fetchDeviceTags:^(NSError * _Nullable error, id _Nullable data) {
       if (!error) {
           NSArray<NSString *> *tags = (NSArray *)data;
           NSLog(@"Device tags: %@", tags);
       }
   }];

5. Fetch application tags (whitelist): Returns the tag names that are configured at the application level. Use this list to validate tag names before assigning them to a device.

   Swift

   Objective-C

   Appoxee.shared()?.fetchApplicationTags { error, data in
       if error == nil, let whitelist = data as? [String] {
           print("Application tags: \(whitelist)")
       }
   }

   [[Appoxee shared] fetchApplicationTags:^(NSError * _Nullable error, id _Nullable data) {
       if (!error) {
           NSArray<NSString *> *whitelist = (NSArray *)data;
           NSLog(@"Application tags: %@", whitelist);
       }
   }];

6. Clear the tags cache: Forces the next fetch to hit the server.

   Swift

   Objective-C

   Appoxee.shared()?.clearTagsCache { error, data in
       if error == nil { print("Tags cache cleared.") }
   }

   [[Appoxee shared] clearTagsCacheWithCompletionhandler:^(NSError * _Nullable error, id _Nullable data) {
       if (!error) {
           NSLog(@"Tags cache cleared.");
       }
   }];

   Warning:

   The Objective-C selector exported by the SDK is clearTagsCacheWithCompletionhandler: — note the lowercase h in Completionhandler. Use the symbol exactly as shown in Objective-C.

Keep in mind:

• Only tag names defined at the application level (fetchApplicationTags:) can be assigned to a device. Adding an unknown tag is a no-op or error depending on backend configuration.

• Use consistent and descriptive tag names so segmentation rules stay legible.

• Test add, remove, and retrieve flows together — including the combined addTagsToDevice:andRemove:withCompletionHandler: form.