iOS CCFrameworkOpen Gamification - scopetech/Mobile-Public GitHub Wiki

iOS CCFrameworkOpen — Gamification

Gamification (G-Zone) in CCFrameworkOpen-iOS: players, games, rounds, experience levels, rewards, currency, badges and leaderboards. All calls are class methods of CCOpenInterface. Installation, initialization and response handling are on the Framework page.

How it works

The backend (G-Zone) evaluates games and rewards. The app requests the current state through the SDK APIs; the backend does not push game events to the app.

Trip recorded by the trip-recording SDK
        │  uploaded
        ▼
Scope backend scores the trip
        │
        ▼
G-Zone updates the player: experience, currency, game rounds and rewards
        │
        │  app requests data (REST, authenticated)
        ▼
CCFrameworkOpen-iOS  ──►  your app UI

A trip is reflected in game data only after it has been uploaded and processed by the backend. The next request after that returns the updated state.

Identifiers

Identifier	How to get it	Used by
Vehicle unit id (pvu)	`String(CCOpenInterface.getSelectedVehicle()!.unitID)`	player info, available games
Policy number	`CCOpenInterface.getSelectedVehicle()?.policyNumber`	player rounds
User id	`String(describing: CCOpenInterface.getCurrentAccount()!.userID)`	user-based variants of games / rounds

Data to load

A gamification screen needs four requests. They are independent and can run in parallel.

API	`rawResponse`	Contains
`getExperienceLevel(_:ignoreCache:completeBlock:)`	Array of objects	Experience level definitions: level name and point range (start/end)
`getPlayerInfo(forVehicleUnitId:complete:)`	Object	The player: experience points and currency balance
`getPlayerAvailableGames(forVehicleUnitId:complete:)`	Array of objects	Games available to the player
`getPlayerGameRounds(forPolicyNumber:complete:)`	Array of objects	The player's game rounds (in progress and completed), including their rewards

User-based alternatives: getPlayerAvailableGames(forUserId:complete:) and getPlayerGameRounds(forUserId:complete:).

The G-Zone payloads are read from response.rawResponse and mapped to the app's own models.

import CCFrameworkOpen_iOS

final class GamificationLoader {
    private(set) var levels: [String: Any](/scopetech/Mobile-Public/wiki/String:-Any) = []
    private(set) var player: [String: Any]?
    private(set) var availableGames: [String: Any](/scopetech/Mobile-Public/wiki/String:-Any) = []
    private(set) var rounds: [String: Any](/scopetech/Mobile-Public/wiki/String:-Any) = []

    func load(completion: @escaping () -> Void) {
        guard let vehicle = CCOpenInterface.getSelectedVehicle() else { return }
        let pvu = String(vehicle.unitID)
        let group = DispatchGroup()

        group.enter()
        CCOpenInterface.getExperienceLevel(vehicle, ignoreCache: true) { [weak self] response in
            defer { group.leave() }
            self?.levels = response?.rawResponse as? [String: Any](/scopetech/Mobile-Public/wiki/String:-Any) ?? []
        }

        group.enter()
        CCOpenInterface.getPlayerInfo(forVehicleUnitId: pvu) { [weak self] response in
            defer { group.leave() }
            self?.player = response?.rawResponse as? [String: Any]
        }

        group.enter()
        CCOpenInterface.getPlayerAvailableGames(forVehicleUnitId: pvu) { [weak self] response in
            defer { group.leave() }
            self?.availableGames = response?.rawResponse as? [String: Any](/scopetech/Mobile-Public/wiki/String:-Any) ?? []
        }

        if let policyNumber = vehicle.policyNumber {
            group.enter()
            CCOpenInterface.getPlayerGameRounds(forPolicyNumber: policyNumber) { [weak self] response in
                defer { group.leave() }
                self?.rounds = response?.rawResponse as? [String: Any](/scopetech/Mobile-Public/wiki/String:-Any) ?? []
            }
        }

        group.notify(queue: .main, execute: completion)
    }
}

Deriving game state

The app derives the game status from the loaded data. The field names below are the ones used by the reference app's models.

Status	Rule
Available	Items returned by the available-games API
In progress	Rounds whose end date (`endOn`) is empty or missing
Completed	Rounds whose end date (`endOn`) is set
Rewards	Rewards of the completed rounds
Currency	Player info: `currency`
Current level	The level whose point range (`levelPointStart`…`levelPointEnd`) contains the player's `experience`
Next level / progress	The next level range; progress = (experience − current start) ÷ (current end − current start). Above the highest range, the player is at the last level.

When to refresh

There is no event or push channel for game updates, so the app must request the data again to pick up changes. Each reload returns the latest state; comparing it with the previous load shows what changed, such as a new round, new rewards, or a round that has completed.

The reference app reloads all four requests:

when the gamification screen is opened
when the user selects another vehicle

Pass ignoreCache: true where available so the result reflects the latest server state.

Other G-Zone APIs

These are available in the package but are not used by the flow above:

API	Contains
`getCurrencyAmount(for:ignoreCache:completeBlock:)`	Currency balance for a vehicle
`getBadges(for:ignoreCache:completeBlock:)` / `getBadges(forVehicleAll:ignoreCache:completeBlock:)`	Badges
`getPlayerGameRounds(_:timeInterval:complete:)`	Rounds within a date range
`getLeaderboards…`, `getAvailableRanks…`, `getUnqualified…Ranks…`	Leaderboards and ranks
`getGzonePlayerGroups(_:complete:)`	Player groups
`getRoundCompletedNotifications(_:)`	Completed-round notifications
`getGZoneResourceUrl(_:)`	URL of a G-Zone image resource

Rewards bought with the currency are handled by the marketplace APIs (getQuantigo…), listed on the Framework page.

API overview

Method	Description
`getPlayerInfoForVehicleUnitId:complete:`	Player: experience and currency
`getGzonePlayerGroups:complete:`	Player groups
`getExperienceLevel:ignoreCache:completeBlock:`	Experience level definitions (name, point range)
`getCurrencyAmountForVehicle:ignoreCache:completeBlock:`	Reward currency balance
`getBadgesForVehicle:ignoreCache:completeBlock:`	Earned badges
`getBadgesForVehicleAll:ignoreCache:completeBlock:`	All badges for the vehicle
`getPlayerAvailableGamesForVehicleUnitId:complete:` / `…ForUserId:complete:`	Available games
`getPlayerGameRoundsForVehicleUnitId:complete:` / `…ForUserId:complete:` / `…ForPolicyNumber:complete:`	Player rounds (in progress and completed) with rewards
`getPlayerGameRounds:timeInterval:complete:`	Player rounds in a time interval
`getRoundCompletedNotifications:`	Completed-round notifications
`getLeaderboards:complete:`, `getAvailableLeaderboards:complete:`, `getAllLeaderboards:`	Leaderboards
`getLeaderboardsRank:leaderboardName:startOn:rankFrom:rankTo:complete:`	Ranks around the player (paged)
`getAvailableRanks:startOn:rankFrom:rankTo:complete:`	Ranks in a leaderboard (paged)
`getUnqualifiedInProgressRanks:…`, `getUnqualifiedAvailableRanks:…`	Unqualified in-progress / available ranks
`getGZoneResourceUrl:`	URL of a G-Zone image resource

Frequently asked questions

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.

The trip-recording SDK records trips and uploads them to the Connected Car backend.
The backend scores each trip. G-Zone then updates the player's state: experience points, currency, game rounds and their rewards.
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.

iOS CCFrameworkOpen — Framework