CCFrameworkOpen-iOS — Gamification Q&A

1. How reward/game information is made available through the SDK / Connected Car

Games and rewards are evaluated on the Scope backend (G-Zone), not on the device.

1. The trip-recording SDK records trips and uploads them to the Connected Car backend.
2. The backend scores each trip. G-Zone then updates the player's state: experience points, currency, game rounds and their rewards.
3. The app requests this state through CCFrameworkOpen-iOS (CCOpenInterface). Each API is an authenticated REST call. The result arrives asynchronously as JSON in CCAPIResponse.rawResponse, which the app maps to its own models.

Data is scoped to the logged-in user and requested by vehicle unit id (pvu), policy number or user id.

A trip is reflected in game data only after the backend has processed it. The next request then returns the updated state.

2. APIs (including G-Zone) that provide game status and reward information

All are class methods of CCOpenInterface.

Used for game status and rewards

API	Returns
getPlayerInfoForVehicleUnitId:complete:	The player: experience points and currency balance
getExperienceLevel:ignoreCache:completeBlock:	Experience level definitions (level name, point range)
getPlayerAvailableGamesForVehicleUnitId:complete:	Games available to the player
getPlayerGameRoundsForPolicyNumber:complete:	The player's game rounds, in progress and completed, with their rewards

User-based variants: getPlayerAvailableGamesForUserId:complete: and getPlayerGameRoundsForUserId:complete:.

The game status is derived from these responses:

Status	Rule
Available	Items returned by the available-games API
In progress	Rounds without an end date (endOn empty)
Completed	Rounds with an end date (endOn set)
Rewards	Rewards of the completed rounds
Current level and progress	The player's experience compared with the level point ranges

Also available

API	Returns
getCurrencyAmountForVehicle:ignoreCache:completeBlock:	Currency balance for a vehicle
getBadgesForVehicle:… / getBadgesForVehicleAll:…	Badges
getPlayerGameRounds:timeInterval:complete:	Rounds within a date range
getLeaderboards:complete:, getLeaderboardsRank:…, getAvailableRanks:…	Leaderboards and ranks
getGZoneResourceUrl:	URL of a G-Zone image (badge icons, game artwork)

3. How a client application can receive game events (start, progress, completion)

Game events are not delivered as notifications. The SDK has no event callback, and the backend does not push game events. The app gets game updates by requesting the data through the APIs above. Each response reflects the latest state on the backend.

Event	How the app detects it
Game start	A new round appears in getPlayerGameRoundsForPolicyNumber:, without an end date (in progress). New games appear in getPlayerAvailableGamesForVehicleUnitId:.
Progress	The round data, the player's experience (getPlayerInfoForVehicleUnitId:) and the currency change as trips are processed
Completion	The round's end date (endOn) is set; its rewards appear in the completed round

When to request the data. The Scope reference app loads all four requests when the gamification screen is opened and when the user changes the selected vehicle. The client app can request the data at any other point where it needs up-to-date status, for example when the app returns to the foreground. To show an event to the user (such as a newly completed round), compare the new response with the previous one.