Type Method

reportAchievements:withCompletionHandler:

Reports progress on an array of achievements.

Declaration

+ (void)reportAchievements:(NSArray<GKAchievement *> *)achievements withCompletionHandler:(void (^)(NSError *error))completionHandler;

Parameters

achievements

An array of GKAchievement objects that contains the achievements whose progress is being updated.

completionHandler

A block to be called after the operation completes.

The block takes the following parameter:

error

If the operation was successful, this value is nil; otherwise, this parameter holds an object that describes the problem that occurred.

Discussion

Use this class method whenever you need to submit one or more achievement updates at the same time. Calling this method reports each of the achievements in the array. Processing multiple achievements at once allows the entire operation to be processed more efficiently using this method as the completion handler is only called once. Listing 1 shows an example of how to report a single achievement.

Listing 1

Reporting progress on an achievement

- (void) reportAchievementIdentifier: (NSString*) identifier percentComplete: (float) percent
{
    GKAchievement *achievement = [[GKAchievement alloc] initWithIdentifier: identifier];
    if (achievement)
    {
         achievement.percentComplete = percent;
         [GKAchievement reportAchievements:@[achievement] withCompletionHandler:^(NSError *error)
         {
              if (error != nil)
              {
                  NSLog(@"Error in reporting achievements: %@", error);
              }
         }];
    }
}

Listing 2 shows an example of how to report multiple achievements for the local player.

Listing 2

Reporting progress on multiple achievements

- (void) completeMultipleAchievements
{
    GKAchievement *achievement1 = [[GKAchievement alloc] initWithIdentifier: @"DefeatedFinalBoss"];
    GKAchievement *achievement2 = [[GKAchievement alloc] initWithIdentifier: @"FinishedTheGame"];
    GKAchievement *achievement3 = [[GKAchievement alloc] initWithIdentifier: @"PlayerIsAwesome"];
    achievement1.percentComplete = 100.0;
    achievement2.percentComplete = 100.0;
    achievement3.percentComplete = 100.0;
 
    NSArray *achievementsToComplete = @[achievement1,achievement2,achievement3];
    [GKAchievement reportAchievements: achievementsToComplete withCompletionHandler:^(NSError *error)
             {
                  if (error != nil)
                  {
                      NSLog(@"Error in reporting achievements: %@", error);
                  }
             }];
    }
}

When this method is called, it creates a new background task to handle the request. The method then returns control to your game. Later, when the task is complete, Game Kit calls your completion handler. The completion handler is always called on the main thread.

See Also

Reporting Progress on Achievements

+ reportAchievements:withEligibleChallenges:withCompletionHandler:

Reports a list of achievements and limits the challenges those achievements may complete.