Audiences

Your company may use audiences to target groups of users in sending push notifications, email campaigns, or advertising campaign. If your organization has audiences enabled, you may fetch audience memberships for the current user. The result returned by the SDK is an array of audience IDs, optionally filtered by given endpoint ID.

User segment requests are done asynchronously and allow a timeout to be specified. When your app makes a user segment request, if for any reason (slow network speed, lack of network coverage, etc) the SDK does not receive a response back within the timeout period specified, the SDK will invoke the completion method with a cached version of the user segment, or with an empty user segment (if the local cache is expired or non-existent). In all cases, once a response containing user segments arrives, it will update the local cache for future requests.

The example shows a request to retrieve segments with the endpoint id “1234567890” and with a timeout of 0.5 seconds (500 milliseconds).

[[MParticle sharedInstance] userSegments:0.5
                              endpointId:@"1234567890"
                       completionHandler:^(MPUserSegments *userSegments, NSError *error) {
                           NSMutableString *userSegmentsDescription = [[NSMutableString alloc] init];
                           if (userSegments) {
                               [userSegmentsDescription appendString:@"user segments: "];
                               [userSegmentsDescription appendString:[userSegments commaSeparatedSegments]];
                           } else {
                               [userSegmentsDescription appendString:@"No User Segments Available."];
                           }
                             
                           [[[UIAlertView alloc] initWithTitle:@"User Segments"
                                                       message:userSegmentsDescription
                                                      delegate:nil
                                             cancelButtonTitle:@"Ok"
                                             otherButtonTitles:nil]
                            show];
                      }];

If segments could not be retrieved or if your company is configured not to allow segments, the callback handler will return an NSError with a reason for the failure.

The SDKs provide convenience methods to concatenate all retrieved segments into a comma-separated string. This is particularly useful to add segments as tags to advertisement banners. For example, if you are using Google Mobile Ads or MoPub you could use one of the following sample codes to tag ads.

Google Mobile Ads

- (void)createRequestWithCompletionHandler:(void(^)(GADRequest *request))completionHandler {
    [[MParticle sharedInstance] userSegments:0.1
                                  endpointId:@"%reference_key%"
                           completionHandler:^(MPUserSegments *userSegments, NSError *error) {
                               if (error == nil) {
                                   GADRequest *request = [GADRequest request];
                                   DFPExtras *extras = [[DFPExtras alloc] init];
                                   extras.additionalParameters = @{@"Age": @"25",
                                                                   @"Color":@"Blue,Green,Red",
                                                                   @"MP-Segments":[userSegments commaSeparatedSegments]};
                                   [request registerAdNetworkExtras:extras];
                                   completionHandler(request);
                               } else {
                                   NSString *message = error.userInfo[@"message"];
                                   NSLog(@"Error with message: %@", message);
                               }
                           }];
}

MoPub

- (void)loadAdView {
    [[MParticle sharedInstance] userSegments:0.1
                                  endpointId:@"%reference_key%"
                           completionHandler:^(MPUserSegments *userSegments, NSError *error) {
                               if (error == nil) {
                                   NSMutableString *keyValueKeywords = [[NSMutableString alloc] init];
                                   
                                   // Creates the key:value pairs
                                   for (NSString *segmentId in userSegments.segmentsIds) {
                                       [keyValueKeywords appendString:@"MP-Segment:"];
                                       [keyValueKeywords appendString:segmentId];
                                       [keyValueKeywords appendString:@","];
                                   }
                                   [keyValueKeywords deleteCharactersInRange:NSMakeRange([keyValueKeywords length] - 1, 1)]; // Removes the trailing comma
                                   
                                   self.moPubAdView.keywords = keyValueKeywords;
                                   [self.moPubAdView loadAd];
                               } else {
                                   NSString *message = error.userInfo[@"message"];
                                   NSLog(@"Error with message: %@", message);
                               }
                           }];
}