iOS CCFrameworkOpen framework

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	CCFrameworkOpen_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 CCFrameworkOpen_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: "CCFrameworkOpen_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 CCFrameworkOpen_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)

// 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).

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.

Session notifications

The SDK posts these notifications through NotificationCenter.default:

Constant	Posted when
kNotificationLogout	The user session ends (logout or expired token). Return the app to its login screen.
kNotificationServerError	The server returns an error response
kNotificationResponseKey	userInfo key of kNotificationServerError that holds the server response

NotificationCenter.default.addObserver(forName: Notification.Name(kNotificationLogout),
                                       object: nil, queue: .main) { _ in
    // show login
}

API reference

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

Initialization and session

Method	Description
initializeWithConfig:	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

Tenant settings, assistance and terms

Method	Description
updateTenantSettingsIfNeeded:	Refresh tenant settings when they are out of date
getTenantPropertiesWithCompleteBlock:	Tenant properties
getSettingsByNames:completeBlock:	Named backend settings
requestAssistanceForVehicle:at:type:location:trigger:complete:	Request roadside assistance for a vehicle
postUsageAdjustments:at:odometer:complete:	Report an odometer adjustment for a vehicle
getTermsAndConditionsMarkdown:	Terms and conditions as Markdown

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 and statistics

Method	Description
getTripsForTimeInterval:ignoreCache:completeBlock:	Trips in an interval
getTripDetailsForTimeInterval:ignoreCache:top:skip:completeBlock:	Trip details, paged
getMZoneTripsForTimeInterval:driverKeyCode:ignoreCache:tripSelect:top:skip:filter:completeBlock:	MZone trips, paged and filtered
getLightTripsForTimeInterval:ignoreCache:completeBlock: / getLightTripsForDate:vehicleUnitID:completeBlock:	Lightweight trip lists
getMZoneTripDetailForTripID:ignoreCache:completeBlock:	Trip detail
getMZoneEventsForTimeInterval:completeBlock: / getMZoneEventTypesCompleteBlock:	Driving events and event types
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:	Upload a batch of trip events

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
getGZoneResourceUrl:	URL of a G-Zone image resource

Rewards marketplace (Quantigo)

Method	Description
getQuantigoMarketPlaceName	Marketplace name configured for the tenant
isQuantigoTokenValid, getQuantigoToken:, resetQuantigoToken	Marketplace session token
getQuantigoMarketplaces:	Marketplaces
getQuantigoAllPublications:, getQuantigoMarketplacePublications:complete:	Offers (publications), all or per marketplace
getQuantigoMarketplaceBalance:complete:, getQuantigoTenantBalance:complete:	Balances
getQuantigoOfferingMetadata:complete:	Offer details
buyQuantigoPublication:complete:	Buy an offer
getQuantigoUserVouchers:	The user's vouchers
getQuantigoMarketplaceStatistics:complete:	Marketplace statistics

Notifications and feedback

Method	Description
getNotificationsWithParameters:policyId:ignoreCache:completeBlock:	Notifications by filter
getNotificationsById:complete:	A single notification
getOOANotifications:ignoreCache:	Out-of-area notifications
sendUserNotification:completeBlock:	Send user feedback (CCFeedbackNotification)

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:

Beacons

Method	Description
getInstalledBeaconForVehicleUnitId:completeBlock:, getDispatchedBeaconsForVehicleUnitId:completeBlock:	Installed and dispatched beacons
installBeaconForVehicleUnitId:withMacAddress:complete:, installBeaconForVehicleUnitId:withMajorId:andMinorId:complete:	Link a beacon to a vehicle
unlinkBeaconForVehicleUnitId:complete:	Unlink the vehicle's beacon
putBeaconWithParameters:complete:	Update a beacon
registerBeaconAsPossibleRecorderWithUUID:majorID:minorID:complete:, deleteBeaconWithUUID:majorID:minorID:complete:	Register / delete a recorder beacon
getBeaconBatteryLevelFor:completeBlock:, postBeaconBatteryLevel:macAddress:reportedOn:complete:	Beacon battery level
postActivityWithOldName:newName:complete:, putActivityWithParameters:complete:, deleteActivityWithName:complete:	Beacon activities

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

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.
• 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 — Gamification
• Release notes