API Index
Overview
Setup
Initialize
Achievements
Challenges
Leaderboards
Scores
Players
Real-Time Game
Turn-Based Game
 
Before you can add Challenges to your game, you must configure Achievements & Leaderboards in iTunes Connect and the GameKit Plugin must be setup as well as initialized.
 
Challenges Commands
Request Register Challenges Listener
Request Unregister Challenges Listener
GameKit Challenge Events
Show Challenges UI
Show Achievement Challenge UI
Show Score Challenge UI
Get Received Challenges
Request Decline Challenge
Send Achievement For Challenge
Send Score For Challenge
 

Request Register Challenges Listener
Comments: Register callback function for all Challenge events. Note that other Game Center Challenge functions should not be called before the Challenge Listener is registered.

Function: request( (string) “registerChallengesListener”, (table) { listener= (function) onChallengesCallback } )
Param Table Keys: (function) listener – A function to receive callback events.
Callback Events:
Event Name: (string) “gameKitLibrary”
Event Type:
(string) “success” – GameKit success event.
Event Properties:
(string) successDescription – GameKit success description string.

 

Request Unregister Challenges Listener
Comments: Unregister callback function for all Challenge events.

Function: request( (string) “unregisterChallengesListener” )
Param Table Keys: none
Callback Events: none

 

GameKit Challenge Events
Comments: GameKit Challenge Events called on local player’s device. Note the Challenges Listener needs to be registered before the local player’s device can receive these events.

Event Name: (string) “gameKitLibrary”
Event Type:
(string) “challengeAccepted” – GameKit Challenge accepted event. Called on local player’s device after local player accepts challenge by tapping on notification banner.
(string) “challengeReceived” – GameKit Challenge received event. Called on local player’s device when local player is currently playing game and receives a challenge from a friend.
(string) “challengeCompleted” – GameKit Challenge completed event. Called on local player’s device when the local player completes a challenge.
(string) “issuedChallengeCompleted” – GameKit issued Challenge completed event. Called on local player’s device when local player’s friend completes a challenge local player sent to friend.
Event Properties:
(table) challenge – Challenge table.
Challenge Table Keys:
(string) challengeType – A name string for the type of challenge, “AchievementChallenge” or “ScoreChallenge”.
(string) issueDate – A date string of the date the challenge was issued.
(string) issuingPlayerID – A player identifier string of the player who issued the challenge.
(string) receivingPlayerID – A player identifier string of the player who received the challenge.
(string) message – A message string that describes the challenge.
(number) state – GameKit GKChallengeState number.
(string) completionDate – A date string of the date the challenge was completed.

 

Show Challenges UI
Comments: Show Game Center Challenges UI.

Function: show( (string) “gameCenterChallengesUI” )
Param Table Keys: none
Callback Events: none

 

Show Achievement Challenge UI
Comments: Show Game Center Achievement Challenge UI to Challenge local player’s Game Center friends to obtain Achievement.

Function: show( (string) “gameCenterAchievementChallengeUI”, (table) { achievementID= (string) “com.yourSite.yourGame.achievement_wow”, message= (string) “Can you get it?”, playerIDs= (table) { (string) “G:2073637149” } } )
Param Table Keys:
(string) achievementID – A unique Game Center achievement identifier string you created for your game on iTunes Connect.
(string) message – A message string that describes the challenge.
(table) playerIDs – An array of 1 or more playerID strings that the challenge is to be sent to.
Callback Events:
Event Name: (string) “gameKitLibrary”
Event Type:
(string) “error” – GameKit error event.
(string) “challengeSent” – Challenge sent event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(number) playersCount – Number of player tables in the players array.
(array) players – Array of player tables.
Player Table Keys: (string) playerID – A string used to identify the player who was sent an Achievement Challenge.

 

Show Score Challenge UI
Comments: Show Game Center Score Challenge UI to Challenge local player’s Game Center friends to beat Score.

Function: show( (string) “gameCenterScoreChallengeUI”, (table) { leaderboardID = (string) “com.yourSite.yourGame.defaultLeaderboard”, message= (string) “Can you beat that?”, playerIDs= (table) { (string) “G:2073637149” , (string) “G:9125286970” } } )
Param Table Keys:
(string) leaderboardID – A unique Game Center leaderboard identifier string you created for your game on iTunes Connect.
(string) message – A message string that describes the challenge.
(table) playerIDs – An array of 1 or more playerID strings that the challenge is to be sent to.
Callback Events:
Event Name: (string) “gameKitLibrary”
Event Type:
(string) “error” – GameKit error event.
(string) “challengeSent” – Challenge sent event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(number) playersCount – Number of player tables in the players array.
(array) players – Array of player tables.
Player Table Keys: (string) playerID – A string used to identify the player who was sent an Achievement Challenge.

 

Get Received Challenges
Comments: Get local player’s received Game Center Challenges.

Function: get( (string) “receivedChallenges” )
Param Table Keys: none
Callback Events:
Event Name: (string) “gameKitLibrary”
Event Type:
(string) “error” – GameKit error event.
(string) “challengeList” – Challenge list event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(number) challengesCount – Number of challenge tables in the challenges array.
(array) challenges – Array of challenge tables.
Challenge Table Keys:
(string) challengeType – A name string for the type of challenge, “AchievementChallenge” or “ScoreChallenge”.
(string) issueDate – A date string of the date the challenge was issued.
(string) issuingPlayerID – A player identifier string of the player who issued the challenge.
(string) receivingPlayerID – A player identifier string of the player who received the challenge.
(string) message – A message string that describes the challenge.
(number) state – GameKit GKChallengeState number.
(string) completionDate – A date string of the date the challenge was completed.

 

Request Decline Challenge
Comments: Decline Game Center Achievement or Score Challenge. To decline a particular Challenge, your game must call get( “receivedChallenges” ) to get the challenge table of the Challenge the local player wants to decline.

Function: request( (string) “declineChallenge”, (table) { challengeType = (string) “AchievementChallenge”, issueDate= (string) “2015-11-28 18:23:57 +0000”, issuingPlayerID= (string) “G:2073637149” } )
Param Table Keys:
(string) challengeType – A name string for the type of challenge, “AchievementChallenge” or “ScoreChallenge”.
(string) issueDate – A date string of the date the challenge was issued.
(string) issuingPlayerID – A player identifier string of the player who issued the challenge.
Callback Events:
Event Name: (string) “gameKitLibrary”
Event Type:
(string) “error” – GameKit error event.
(string) “success” – GameKit success event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(string) successDescription – GameKit success description string.

 

Send Achievement For Challenge
Comments: Send Game Center local player’s Achievement progress for Achievement Challenge.

Function: (function) send( (string) “achievementForAchievementChallenge”, (table) { achievementID= (string) “com.yourSite.yourGame.achievement_wow”, percentComplete= (number) 100.0, showsCompletionBanner= (boolean) true } )
Param Table Keys:
(string) achievementID – A unique Game Center achievement identifier string you created for your game on iTunes Connect.
(number) percentComplete – A percentage decimal number value between 0.0 and 100.0 of how far the local player has progressed on this achievement.
(boolean) showsCompletionBanner – A boolean value that states whether a notification banner is displayed when the achievement is completed.
Callback Events:
Event Name: (string) “gameKitLibrary”
Event Type:
(string) “error” – GameKit error event.
(string) “success” – GameKit success event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(string) successDescription – GameKit success description string.

 

Send Score For Challenge
Comments: Send Game Center local player’s Score for Score Challenge. Note the optional param key, context, is not required.

Function: (function) send( (string) “scoreForScoreChallenge”, (table) { leaderboardID= (string) “com.yourSite.yourGame.defaultLeaderboard”, value= (number) 68, (optional key) context= (number) 42 } )
Param Table Keys:
(string) leaderboardID – A unique Game Center leaderboard identifier string you created for your game on iTunes Connect.
(number) value – A score number value earned by the local player. You determine how your scores are formatted when you define the leaderboard on iTunes Connect.
(number) context (optional key) – A number value used by your game. The context property is stored and returned to your game, but is otherwise ignored by Game Center. It allows your game to associate an arbitrary 64-bit unsigned integer value with the score data reported to Game Center. You decide how this context value is interpreted by your game.
Callback Events:
Event Name: (string) “gameKitLibrary”
Event Type:
(string) “error” – GameKit error event.
(string) “success” – GameKit success event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(string) successDescription – GameKit success description string.