• BlackBerry Dynamics
  • Runtime library for iOS applications
  • 9.0.0.75
BAFBlackberryAnalytics Class Reference

Class for BlackBerry Analytics and BlackBerry Persona. More...

#import <BAFBlackberryAnalytics.h>

Inherits NSObject.

Description

BlackBerry Analytics

BlackBerry Analytics provides developers and UEM administrators metrics about the BlackBerry Dynamics apps and devices in an organization's environment. BlackBerry Dynamics apps with this feature enabled by their administrator will periodically send events (including startup, crash information) and data (including OS, minutes used, app name, version) to the BlackBerry Analytics platform. The BlackBerry Analytics platform processes and compiles the events and data into dashboard reports. An app developer can optionally use this programmatic interface to record usage of custom features or events within their app to enable these metrics to be included within the Analytics dashboard.

For more information, see the BlackBerry Analytics documentation.

BlackBerry Persona

BlackBerry Persona processes events and location data from BlackBerry Dynamics apps to assess a user’s security risk level based on their real-world context, and adjusts the user’s device and app behavior based on their current risk level. For example, if a user’s app data reports a geographic location that is not typical for the user, BlackBerry Persona can dynamically limit the user’s access to work apps or disable certain device features such as the camera. In addition, it can be configured by the enterprise administrator to enforce stricter authentication requirements by applying an override policy.

This service requires enabling and configuration by the enterprise administrator. In addition, application developers are required to perform steps to enable BlackBerry Persona.

Enabling BlackBerry Persona

Implement these step to enable Persona within a BlackBerry Dynamics application.

1. Add the following custom properties to the Info section of your project target in Xcode. The resulting Info.plist file should contain:

<dict>
<key>BlackBerryDynamics</key>
<dict>
<key>EnableBlackBerryPersona</key>
<true/>
</dict>
</dict>

2. Add a setting in the application user interface for end users to enable or disable BlackBerry Persona.

This setting should ideally be implemented within the 'Settings' or 'Preferences' section of your application's user interface. When the user selects a menu item called 'BlackBerry Persona Settings' the application should call the method displaySISsettings (BAFBlackberryAnalytics). This triggers the runtime to display a settings screen which provides the user the option to opt in or out of using location based information when assessing their current risk level. This is a legal requirement to ensure end users are able to opt out of location data collection at any time. It is best practice to only show this option to users who have BlackBerry Persona enabled by their administrator, see isSISenabled (BAFBlackberryAnalytics).

For more information, see the BlackBerry Persona documentation.

Class Methods

(void) + trackFeatureEvent:withFeatureName:completion:
 Record feature events to analyse the period a specific app feature is used. More...
 
(void) + trackApplicationEvent:withValue:forKey:completion:
 Record adoption events to analyse the frequency of specific user actions or events. More...
 
(void) + trackSecurityEvent:withEventValue:
 Register a security event which will trigger BlackBerry Persona risk analysis. More...
 
(void) + trackAppUsagePattern:version:data:completion:
 Track App Usage events to detect anomalies in user behaviour. More...
 
(BOOL) + isSISenabled
 Determine if BlackBerry Persona is enabled for the current user by their administrator. More...
 
(void) + displaySISsettings
 Show a settings screen to enable the user to manage BlackBerrry Persona. More...
 
(void) + sendGDAppEvent:
 Deprecated method. More...
 
(NSString *_Nonnull) + getAnalyticsVersion
 Deprecated method. More...
 
(void) + hostInitializationCompleted:
 Deprecated method. More...
 
(void) + setStage
 Deprecated method. More...
 
(NSString *_Nullable) + getThreatLevel
 Deprecated method. More...
 
(NSDictionary *_Nullable) + getThreatDetails
 Deprecated method. More...
 

Method Documentation

◆ trackFeatureEvent:withFeatureName:completion:

+ (void) trackFeatureEvent: (BAFAnalyticsEvent event
withFeatureName: (NSString *_Nonnull)  featureName
completion: (_Nullable BAFAnalyticsResponseCompletion completion 

Call to record an event that has a start point (a "feature active event") followed by a stop point (a "feature inactive event"). The start and stop points provide a period of time where the feature was active. This type of event is typically used to measure user engagement of app features. The name that is used to track a feature must be unique within the app.

Parameters
eventBAFAnalyticsEvent specifies the type of event. For example, FEATURE_ACTIVE or FEATURE_INACTIVE.
featureNameNSString containing the name of the feature for a given event.
completionThe completion block to be invoked when the operation completes. BAFAnalyticsResponse will return RECORD_SUCCESS if event is valid or a specific error otherwise.

◆ trackApplicationEvent:withValue:forKey:completion:

+ (void) trackApplicationEvent: (BAFAnalyticsEvent event
withValue: (NSString *_Nonnull)  eventValue
forKey: (NSString *_Nonnull)  eventKey
completion: (_Nullable BAFAnalyticsResponseCompletion completion 

Call to record an event which occurs in your application. An adoption event has two attributes, key and value. The key must be unique within the app, and the value is a count of the number of times a specific event occurs (for example, an event key called "Emails deleted" that tracks the number of emails deleted by a user). The adoption event value should be the string representation of the integer count. An app can combine events and record a single event.

Parameters
eventAnalyticsEvent specifies the type of event. In this case use ADOPTION_EVENT.
eventValueNSString containing the event value to record for the given event key.
eventKeyNSString to define the name of the event.
completionThe completion block to be invoked when the operation completes. BAFAnalyticsResponse will return RECORD_SUCCESS if event is valid or a specific error otherwise.

◆ trackSecurityEvent:withEventValue:

+ (void) trackSecurityEvent: (BAFSecurityEventType eventType
withEventValue: (NSString *_Nullable)  eventVal 

BlackBerry Persona risk analysis is performed by default when an application is brought to the foreground. To trigger risk analysis at other points in your application life-cycle, use this method to register the appropriate events. For example, your application could trigger risk analysis if a file is shared, money is transferred, or data is deleted.

Call this method setting the eventVal to correspond with the specific application event which should trigger risk analysis, e.g. 'SHARE_FILE'. Set SecurityEventType to SECURITY_ADOPTION_EVENT or other appropriate SecurityEventType. After you've successfully registered the security event, all subsequent calls, in this example, to trackApplicationEvent with the eventKey of 'SHARE_FILE' will trigger BlackBerry Persona risk analysis.

Parameters
eventTypeSpecifies BAFSecurityEventType which event type should be security event.
eventValSpecifies name/label to associate with security event.

◆ trackAppUsagePattern:version:data:completion:

+ (void) trackAppUsagePattern: (BISAppUsageEventType eventType
version: (NSUInteger)  version
data: (NSDictionary< NSString *, NSObject * > *_Nonnull)  appData
completion: (_Nullable BAFAnalyticsResponseCompletion completion 

BlackBerry Persona can perform enhanced risk analysis and continuous authentication by tracking anomalies in user behavior. The risk engine can detect a user's anomalous app usage behavior and enforce user identity either by requiring a user to re-authenticate to confirm their identity, or by applying predefined policy.

Parameters
eventTypespecifies BISAppUsageEventType.
versionspecifies track api version.
appDataspecifies app usage data of app feature.
completionThe completion block to be invoked when the operation completes.

To instrument user actions in your application, construct the following information to send within appData:

JSON Schema

The following schema applies to the payload sent within appData

appData:
type: object
description: Record data for model generation and scoring based on app usage
required:
- module
- moduleVersion
- eventTs
- eventType
properties:
module:
type: string
description: App feature/module which the event corresponds to.
example: 'email'
moduleVersion:
type: string
description: Schema version of the payload. This version along with the application identifier is used by BlackBerry Persona service to process the payload.
example: '1.0'
eventTs:
type: integer
format: int64
description: Time-stamp of the event expressed as an epoch.
example: 994953488910
eventType:
type: string
description: The type of custom action performed by the user within a module.
example: 'SHARE'
event:
description: Optional object to include additional details related to an event. For example a search string or attributes of a file being shared.
type: object
additionalProperties:
description: Event specific fields (object type is a map)
type: object

Module

If your application contains disparate capabilities, subdivide these into modules, e.g. payments, email, editor.

EventType

Identify a set of custom eventTypes which correspond to specific user actions within each module. The following are examples of events that you may wish to track.

  • COPY
  • DELETE
  • FORWARD
  • DOWNLOAD
  • OPEN_IN
  • REPLY
  • SCREEN_SHOT
  • SCROLL_DOWN
  • SCROLL_UP
  • SEARCH
  • SEND
  • SHARE
  • SWIPE_LEFT
  • SWIPE_RIGHT

Example Payload

The following is an example of JSON payload for appData.

{
"eventType": "SWIPE_RIGHT",
"module": "email",
"moduleVersion": "1.0",
"eventTs": 1580938248291
},
{
"eventType": "DELETE",
"module": "filemanager",
"moduleVersion": "1.0",
"eventTs": 1580938248705
}

◆ isSISenabled

+ (BOOL) isSISenabled

Call this method to determine if BlackBerry Persona is enabled for the current user. For help see 'Steps to configure and use BlackBerry Persona' within the BlackBerry Persona documentation.

◆ displaySISsettings

+ (void) displaySISsettings

Show a settings screen to enable the user to manage BlackBerrry Persona. The settings screen provides the user the option to opt in or out of using location based information when assessing their current risk level. The settings can only be changed if BlackBerry Persona is enabled for the user by the administrator.

◆ sendGDAppEvent:

+ (void) sendGDAppEvent: ((deprecated("Remove sendGDAppEvent: no longer required from this version")))  __attribute__
Deprecated:
This method is deprecated and will be removed in a future release.

◆ getAnalyticsVersion

+ (NSString * _Nonnull) getAnalyticsVersion

Returns SDK version.

Returns
version NSString representation
Deprecated:
now returns the BlackBerry Dynamics SDK version. Will be removed in a future release. See getVersion (GDiOS) class.

◆ hostInitializationCompleted:

+ (void) hostInitializationCompleted: ((deprecated("Will be removed in a future release. There is no replacement for this method call.")))  __attribute__

Implementation now does nothing.

Method remains for compatibility support only

Deprecated:
Will be removed in a future release. There is no replacement for this method call.

◆ setStage

+ (void) setStage

Implementation now does nothing.

Method remains for compatibility support only.

Deprecated:
Will be removed in a future release. There is no replacement for this method call.

◆ getThreatLevel

+ (NSString *_Nullable) getThreatLevel

Returns the currently identified threat level determined by BlackBerry Persona.

Threat level will contain following values: LOW app state is identified as low risk. MEDIUM app state is identified as medium risk. HIGH app state is identified as high risk. CRITICAL app state is identified as critical risk. nil when threat level is not available.

Returns
returns value of type NSString which specifies current threat level.
Deprecated:
Will be removed in a future release. Use BBDThreatStatus API instead
See also
- getOverallThreatLevel (BBDThreatStatus)
- getRiskLevel (BBDThreat)
- getRiskLevel (BBDThreat)

◆ getThreatDetails

+ (NSDictionary *_Nullable) getThreatDetails

Provides detailed threat information for each Persona risk engine. Applications may choose to take action on various threat factors based on the details provided.

Returns
JSONObject which contains the threat details or null.
Deprecated:
Will be removed in the future release. Use BBDThreat API instead
See also
BBDThreatStatus
BBDThreatGeoZone
BBDThreatIdentity

The documentation for this class was generated from the following file:
file
package com good gd file
Definition: doc/GDFileSystem.h:7