Adding Achievements to Your iOS Game

This guide shows you how to use the achievements APIs in an iOS application to unlock and display achievements in your game.

Creating achievements

If you haven't already done so, review the Achievements guide, and create some achievements for your game in the Google Play Developer Console.

Important classes

Here are some important classes that you should know about for displaying and recording achievements:

  • GPGAchievement is used to unlock an achievement, or make progress towards unlocking a particular achievement.
  • GPGAchievementMetadata stores data about an achievement, such as its name, icon, and description, and the player's progress towards unlocking it.

Displaying the achievements list

The Games iOS SDK supports the ability to display an achievements list for a player. Use the GPGLauncherController if you want to display the player's progress towards earning various achievements in your game.

To show the achievements list (for example, in a target action in response to a button click), call presentAchievmentList.

- (IBAction)showAchievements:(UIButton *)sender {
    [[GPGLauncherController sharedInstance] presentAchievementList];
}

Revealing achievements

To reveal (but not unlock) a previously hidden achievement:

  1. Get the GPGAchievement object by calling GPGAchievement +achievementWithId.

    // You get this string from the Developer Console
    const NSString *achievementId = @"abcdefg1234567";
    GPGAchievement *revealMe = [GPGAchievement achievementWithId:achievementId];
    
  2. Call that achievement's revealAchievementWithCompletionHandler method.

    [revealMe  revealAchievementWithCompletionHandler:^(GPGAchievementState state, NSError *error) {
      if (error) {
        // Handle the error
      } else {
        // Achievement revealed!
      }
    }];
    

Unlocking achievements

You should unlock an achievement whenever the condition for earning that achievement has been met, even if you think the player has unlocked that achievement already. The library takes care of detecting whether or not the achievement has already been unlocked, intelligently caching achievement data, and so on. No extra logic is required on your part.

To unlock an achievement for a user:

  1. Get the GPGAchievement object by calling GPGAchievement +achievementWithId.

    // You get this string from the Developer Console
    const NSString *achievementId = @"abcdefg1234567";
    GPGAchievement *unlockMe = [GPGAchievement achievementWithId:achievementId];
    
  2. Call that achievement's unlockAchievementWithCompletionHandler method.

    [unlockMe unlockAchievementWithCompletionHandler:^(BOOL newlyUnlocked, NSError *error) {
      if (error) {
        // Handle the error
      } else if (!newlyUnlocked) {
        // Achievement was already unlocked
      } else {
        NSLog(@"Hooray! Achievement unlocked!");
      }
    }];
    

Incremental achievements

To update a player's progress towards unlocking an incremental achievement:

  1. Get the GPGAchievement object by calling GPGAchievement +achievementWithId.

    // You get this string from the Developer Console
    const NSString *achievementId = @"abcdefg1234567";
    GPGAchievement *incrementMe = [GPGAchievement achievementWithId:achievementId];
    
  2. Call that achievement's incrementAchievementNumSteps:completionHandler method.

    [incrementMe incrementAchievementNumSteps:2
                            completionHandler:^(BOOL newlyUnlocked, int currentSteps, NSError *error) {
              if (error) {
                // Handle the error
              } else if (newlyUnlocked) {
                 NSLog(@"Incremental achievement unlocked!");
              } else {
                 NSLog(@"User has completed %i steps total", currentSteps);
              }
    }];
    

Customizing achievement notifications

The Achievement Unlocked notification, or "toast," has a consistent behavior and appearance across all games that use the Play Games SDK. There are, however, a few small adjustments you can make to alter the layout of these interface elements.

Changing the notification location

By default, the Achievement Unlocked toasts will appear at the bottom of your game screen. To display this notification in a different location, change the achievementUnlockedToastPlacement and the achievementUnlockedOffset properties of the GPGManager class.

For instance, the following code shows how to move your achievement toast to the top of the game screen instead of the bottom.

    // Specify that our offset is relative to the top of the screen
    [GPGManager sharedInstance].achievementUnlockedToastPlacement = kGPGToastPlacementTop;
    // Specify our offset to be 20 points
    [GPGManager sharedInstance].achievementUnlockedOffset = 20;

Supporting different orientations

By default, the Achievement Unlocked notifications are displayed in portrait orientation. If your game uses landscape mode, they will appear sideways. To correct this, you can alter the validOrientationFlags property of the GPGManager class to restrict or allow whatever orientations you'd like.

      // This allows all orientations except for PortraitUpsideDown
      [GPGManager sharedInstance].validOrientationFlags =
        (1 << UIDeviceOrientationLandscapeLeft) |
        (1 << UIDeviceOrientationLandscapeRight) |
        (1 << UIDeviceOrientationPortrait);

Hiding notifications

To hide the Achievement Unlocked notification entirely, set the GPGAchievement's showsCompletionNotification property to NO. Note that unlike the previous two code samples, this call will only affect individual achievement toasts.

      GPGAchievement *unlockMe = [GPGAchievement achievementWithId:achievementId];
      unlockMe.showsCompletionNotification = NO;

      // Unlock achievement like before
      [unlockMe unlockAchievementWithCompletionHandler ...

Retrieving achievement data

To build your own achievement controller instead of using the one displayed by the library, use the GPGAchievementMetadata class to retrieve achievement data that you want to display.

  [GPGAchievementMetadata allMetadataWithCompletionHandler:
          ^(NSArray *metadata, NSError *error) {
      if (error){
          // Something went wrong.
      } else {
         // Success! Metadata is an array of GPGAchievementMetadata objects
      }
  }];

Enviar comentarios sobre…

Play Games Services for iOS
Play Games Services for iOS