Skip to content

iOS CCFrameworkOpen framework

Jump to bottom
YuliyaArtsiomchykScope edited this page Oct 1, 2026 · 5 revisions

iOS CCFrameworkOpen — Framework

CCFrameworkOpen-iOS gives client apps access to the Scope Connected Car backend. The public API is the Objective-C class CCOpenInterface, usable from Swift and Objective-C. Gamification is described on its own page: iOS CCFrameworkOpen — Gamification.

  |   -- | -- Swift package | CCFrameworkOpenSPM-iOS Product | CCFrameworkSPM_Open_iOS Module | CCFrameworkOpen_iOS Binary | CCFrameworkOpen-iOS.xcframework Minimum iOS | 15.6

SDCompleteBlock → OSCompleteBlock. The response is now nullable in Swift.

Notes and limitations

  • Games and rewards are evaluated on the backend. The app only derives display state (status split, current level) from the API data.
  • No game notifications. Game updates are obtained by requesting the data again; see When to refresh.
  • Deprecated/removed: getPlayerTransactionsForVehicleUnitId (no-op in the core framework). The Quantigo marketplace APIs were removed, except getQuantigoMarketPlaceName.
  • This is the open distribution. Endpoints written for one named customer are not part of the public API; the generic equivalents are.
  • Network logging. Requests and responses are logged to the console at info level. The internal logging hooks used by Scope apps are not part of this build.
  • Dispatch UI updates from completion blocks to the main queue explicitly.

Related pages

# iOS CCFrameworkOpen — Framework

CCFrameworkOpen-iOS gives client apps access to the Scope Connected Car backend. The public API is the Objective-C class CCOpenInterface, usable from Swift and Objective-C. Gamification is described on its own page: [iOS CCFrameworkOpen — Gamification](iOS-CCFrameworkOpen-Gamification).
Swift package CCFrameworkOpenSPM-iOS
Product CCFrameworkSPM_Open_iOS
Module CCFrameworkOpen_iOS
Binary CCFrameworkOpen-iOS.xcframework
Minimum iOS 15.6

Requirements
Platform iOS 15.6 or later
Architectures device arm64; simulator arm64 (Apple-silicon Macs)
Languages Swift, Objective-C
Module CCFrameworkOpen_iOS
Distribution Swift Package Manager, binary XCFramework

A backend environment (base URL, URL suffix, protocol) and user credentials are provided by Scope Technologies.

Installation

Xcode: File → Add Package Dependencies…, enter the repository URL and add the product CCFrameworkSPM_Open_iOS to your app target:

https://github.com/scopetech/CCFrameworkOpenSPM-iOS.git

Package.swift:

dependencies: [
    .package(url: "https://github.com/scopetech/CCFrameworkOpenSPM-iOS.git", from: "<version>")
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "CCFrameworkSPM_Open_iOS", package: "CCFrameworkOpenSPM-iOS")
        ]
    )
]

Import the module:

import CCFrameworkOpen_iOS
@import CCFrameworkOpen_iOS;

The package name, the product name and the module name differ: you add the package CCFrameworkOpenSPM-iOS, link the product CCFrameworkSPM_Open_iOS, and import the module CCFrameworkOpen_iOS.

Quick start

The order is: initialize → log in → select vehicle → call APIs.

import CCFrameworkOpen_iOS

// 1. Initialize once, before login (e.g. in application(_:didFinishLaunchingWithOptions:))
let config = CCConfig()
config.baseUrl = "<base-url>"
config.urlSuffix = "<url-suffix>"
config.urlProtocol = "https://"
config.resetTokenAutomatically = true

CCOpenInterface.initialize(with: config) { ready, error in
    guard ready else { print("Init failed: \(String(describing: error))"); return }
}

// 2. Log in
CCOpenInterface.login(withUsername: username,
                            password: password,
                            policyNr: nil) { response in
    guard let response, response.success else {
        print("Login failed: \(String(describing: response?.error))")
        return
    }

    // 3. Load account and select a vehicle
    CCOpenInterface.getAccountByIgnoringCache(false) { _ in
        if let vehicle = CCOpenInterface.getVehicles().first as? CCVehicle {
            CCOpenInterface.selectVehicle(vehicle)
        }
    }
}

// Session state
CCOpenInterface.isAuthorized()
CCOpenInterface.getSelectedVehicle()
CCOpenInterface.logout()

Swift names. The Objective-C selectors are imported into Swift using the standard Clang renaming rules, e.g. getBadgesForVehicle:ignoreCache:completeBlock: becomes getBadges(for:ignoreCache:completeBlock:). Xcode's generated interface for CCOpenInterface.h (Jump to Definition) shows the exact Swift signatures.

Responses and error handling

Every network call is asynchronous and returns a CCAPIResponse through OSCompleteBlock:

typedef void (^OSCompleteBlock)(CCAPIResponse * _Nullable response);
Property Meaning
success YES when the request succeeded
error NSError for failed requests
httpStatusCode HTTP status returned by the backend
parsedObject Response mapped to an SDK model, where the endpoint has one
rawResponse Raw JSON from the backend. The G-Zone APIs are read from here (see [Gamification](iOS-CCFrameworkOpen-Gamification)).

The response itself is nullable. Always unwrap it before reading its properties:

CCOpenInterface.getCurrencyAmount(for: vehicle, ignoreCache: true) { response in
    guard let response, response.success else { return }
    let payload = response.parsedObject ?? response.rawResponse
    // update UI on the main thread
}

Methods with an ignoreCache: parameter can return cached data. Pass true when the UI must reflect the latest server state, for example after a trip.

API reference

All methods are class methods on CCOpenInterface. Completion blocks are OSCompleteBlock unless stated otherwise.

Initialization and session

Method Description
initializeWithConfig: / initializeWithConfig:readyBlock: Configure the backend environment. Call before login.
loginWithUsername:password:policyNr:completeBlock: Log in. policyNr is optional.
isAuthorized YES if a user session exists
logout End the session

Account

Method Description
getAccount: / getAccountByIgnoringCache:completeBlock: Load the account, including its vehicles
getCurrentAccount Cached CCAccount (nullable)
getUserId, getUsername, displayName Current user info
getCurrentServerUrl Active backend URL
getUniqueDeviceIdentifierAsString Device identifier used by the SDK
updateAccountEmail:completeBlock: Change email
changePassword:oldPassword:completeBlock: Change password
resetPassword:completeBlock:, sendNewPasswordWithCode:password:completeBlock:, sendNewPassword:confirmPassword:token:completeBlock: Password reset flow
deleteProfile: GDPR profile deletion request
updatePushNotificationToken:completeBlock: Register the APNs token

Registration and OTP

Method Description
registerWithPolicyNumber:email:password:complete: Register with a policy number
registerWithShareCode:email:password:complete: Register with a vehicle share code
registerWithUsername:email:phone:gender:yearOfBirth:zipCode:termsDate:api:complete: Register with a profile
loginWithPhone:username:api:complete: / loginWithCode:username:requestId:api:complete: OTP login: request a code, then verify it

Settings and thresholds

Method Description
getMobileSettings: Mobile settings (CCMobileSettings)
getMProfilerSettingsWithCompleteBlock: Trip-profiler settings
getAccelerationThreshold, getBrakingThreshold, getCorneringThreshold Event thresholds

Vehicles and sharing

Method Description
getVehicles, selectVehicle:, getSelectedVehicle Vehicle list and the active vehicle
getVehicleDetailsForVehicle:ignoreCache:completeBlock: Vehicle details
updateVehicleDetailsForVehicle:policyId:odometerUnit:completeBlock: Update vehicle details
getLastKnownPosition:ignoreCache:completeBlock: Last known position
requestOdometerValue: Odometer value
getUsersForVehicle:completeBlock: Users sharing a vehicle
getSharesWithCompleteBlock:, getVehicleSharingCode:, addShareCode:completeBlock:, revokeVehicleShare:forUser:completeBlock:, unsubscribeFromVehicle:completeBlock: Vehicle sharing

Trips, statistics and scores

Method Description
getTripsForTimeInterval:ignoreCache:completeBlock: Trips in an interval
getLightTripsForTimeInterval:ignoreCache:completeBlock: / getLightTripsForDate:vehicleUnitID:completeBlock: Lightweight trip lists
getMZoneTripDetailForTripID:ignoreCache:completeBlock: Trip detail
getMZoneEventsForTimeInterval:completeBlock: / getMZoneEventTypesCompleteBlock: Driving events and event types
getMZoneScoreForTimeInterval:ignoreCache:completeBlock: Driving score
getStatsForTimeInterval:ignoreCache:completeBlock: Statistics
getDashboardStatisticsForLastWeekWithCompleteBlock: Last-week dashboard
getFeedbackForTimeInterval:…, getExpresionsForTimeInterval:… Driver feedback and expressions
markTripWithId:markAsBusiness:completeBlock: Mark a trip as business/private
postTripEventBatch:completeBlock:, postReportDriverConflict:completeBlock:, sendPreTripConflictWithUnitSerialNumber:tripId:complete: Trip event and driver-conflict reporting

Gamification (G-Zone)

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
setAvatarKey:completeBlock:, getUserAvatar:completeBlock: Avatar
getGZoneResourceUrl: URL of a G-Zone image resource

Notifications

Method Description
getNotificationsWithParameters:policyId:ignoreCache:completeBlock: Notifications by filter
getOOANotifications:ignoreCache: Out-of-area notifications

POI (places and rules)

getUserPlaces:ignoreCache:, getUserPlacesWithPvu:completeBlock:ignoreCache:, createUserPlace:completeBlock:, updateUserPlace:completeBlock:, deleteUserPlaceWithId:completeBlock:, createUserRule:completeBlock:, updateUserRule:completeBlock:, getUserRulesOfType:policyVehicleUnitId:completeBlock:ignoreCache:, deleteUserRuleWithId:completeBlock:, getActivationsForUserRule:completeBlock:, getIsEffectiveForUserRule:completeBlock:, activateUserRuleWithId:policyVehicleUnitId:deviceToken:completeBlock:

Beacons and firmware

getBeaconsWithCompleteBlock:, getInstalledBeaconForVehicleUnitId:completeBlock:, installBeaconForVehicleUnitId:withMacAddress:complete:, installBeaconForVehicleUnitId:withMajorId:andMinorId:complete:, unlinkBeaconForVehicleUnitId:complete:, postBeaconBatteryLevel:macAddress:reportedOn:complete:, putBeaconWithParameters:complete:, registerBeaconAsPossibleRecorderWithUUID:majorID:minorID:complete:, deleteBeaconWithUUID:majorID:minorID:complete:, getBeaconConfiguration, getActivitiesWithCompleteBlock:, postActivityWithOldName:newName:complete:, putActivityWithParameters:complete:, deleteActivityWithName:complete:, firmwareUpdateAvailable:manufacturer:firmware:complete:, downloadFirmwareFile:complete:progress:

Fuel (total cost of ownership)

getFuelEntryWith:complete:, addFuelEntryWith:…, updateFuelEntryWith:…, deleteFuelEntryWith:complete:, fuelEntriesSummaryWith:timeInterval:complete:, fuelEntriesSummaryDetailsWith:timeInterval:complete:, fuelEntriesConfigurationWith:complete:, updateFuelEntriesConfigurationWith:quantity:odomert:complete:

Generic

Method Description
getSomethingFromURL:parameters:httpMethod:ignoreCache:completeBlock: Authenticated call to any backend path
sendMultipartData:to:fileName:complete: Multipart upload

Migrating from SDApiManager

SDApiManagerInterface CCOpenInterface
initializeWithConfig:urlSuffix:urlProtocol: Build a CCConfig (set resetTokenAutomatically = YES) → initializeWithConfig:
loginWithUsername:password:completeBlock: loginWithUsername:password:policyNr:completeBlock: (policyNr: nil)
getAccountWithCompleteBlock: getAccountByIgnoringCache:NO completeBlock:
getAllVehicles getVehicles
pvu getSelectedVehicle.unitID
userId getUserId.integerValue
username getUsername
vehicleName getSelectedVehicle.friendlyName
unitSerialNumber getSelectedVehicle.unitSerialNumber
baseUrl getCurrentServerUrl (full URL)
All other methods Same selector

SDCompleteBlock → OSCompleteBlock. The response is now nullable in Swift.

Notes and limitations

  • Games and rewards are evaluated on the backend. The app only derives display state (status split, current level) from the API data.
  • No game notifications. Game updates are obtained by requesting the data again; see [When to refresh](iOS-CCFrameworkOpen-Gamification#when-to-refresh).
  • Deprecated/removed: getPlayerTransactionsForVehicleUnitId (no-op in the core framework). The Quantigo marketplace APIs were removed, except getQuantigoMarketPlaceName.
  • This is the open distribution. Endpoints written for one named customer are not part of the public API; the generic equivalents are.
  • Network logging. Requests and responses are logged to the console at info level. The internal logging hooks used by Scope apps are not part of this build.
  • Dispatch UI updates from completion blocks to the main queue explicitly.

Related pages

Documentation

Home

Android Frameworks

Consolidated SDK

SmartDrive

PortalApiBase

PortalApiClient

Wellness

SBeacon

iOS Frameworks

Consolidated SPM

SDApiManager

CCFrameworkOpen

SmartDrive

SBeacon

Clone this wiki locally