Skip to content

Latest commit

 

History

History
560 lines (439 loc) · 25.4 KB

DESIGNDOC.md

File metadata and controls

560 lines (439 loc) · 25.4 KB
Raw

Sift iOS SDK

Mobile IOS SDK Software Design Documentation

Table of Contents

1 Overview

2 High Level Class Diagram

3 Data Models

4 Modules

5 Flow Chart

1 Overview

The sift-ios Mobile SDKs collect and send device information and app life cycle events to Sift. Objective C will be used as the programming language and Xcode will be used as the IDE. SDK will be supporting ios 9.2 as deployment target.

The specific features used are: CoreMotion, BatteryManager, Location, NetworkInterface and TelephonyManager. The SDK uses CoreMotion, BatteryManager, Location and NetworkInterface for collecting AppState details. The Device properties details are collected with the help of TelephonyManager and PackageManager along with Build details. In particular, event collecting, appending and uploading are handled on a separate thread with the help of Executors. The Mobile SDKs allow mobile applications to collect and send device properties and application lifecycle events to Sift.

A high-level block diagram is shown

  1. IOS app loads the SDK with the Sift configurations.
  2. The sift SDK will collect and send events to the Sift server when there are events to upload.

This document describes the data models,classes for handling events, and specific flows, respectively.

2 High Level Class Diagram

Class Diagram for App State Collector shown below:

3 Data Models

The data models is to understand the responsibility (attributes and methods) of each class that should be clearly identified.

3.1 SiftEvent

The SiftEvent mainly collects the following information:

  • time : {type: int64_t}
    • It indicates the time (in ms since the unix epoch) that this event occurred. Default value is now.
  • type : {type: string}
    • It indicates the mobile event type. Default value is nil.
  • path : {type: string}
    • It indicates the event path. Default value is nil.
  • userId : {type: string}
    • It indicates the user ID. If not set, the event queue will use the user ID set in the shared Sift object.
  • installationId : {type: string}
    • The installation id indicates the 64-bit number (expressed as a hexadecimal string) unique ID to each device.
  • fields : {type: string}
    • It indicates custom event fields; both key and value must be string typed. Default value is nil.
  • iosDeviceProperties : {type: DevicePropertiesCollector}
    • The ios device property indicates the device related properties as mentioned in section 3.2
  • iosAppState : {type: AppStateCollector}
    • The ios app state indicates the application related datas as mentioned in section 3.3.
  • metrics : {type: string}
    • It indicates the internal metrics. Default value is nil.

Class diagram of SiftEvent:

3.2 DeviceProperties

The iOSDeviceProperties collects the following information:

  • app_name : {type: string}
    • The app name indicates the name of the application in which the sift SDK is used.
  • app_version : {type: string}
    • The app version indicates the current version name of the application in which the sift SDK is used.
  • sdk_version : {type: string}
    • The sdk version indicates the current version of the sift SDK that has been used in the application.
  • device_name : {type: string}
    • It indicates device name.
  • device_model : {type: string}
    • The device model indicates the end-user-visible model name for the end product.
  • device_ifa : {type: string}
    • Identifier for Advertisers (IFA or IDFA) is a temporary device identifier used by the Apple set of handheld devices. A successor of Unique Device Identifier (UDID), IFA is available on all devices with versions iOS 6 and later..
  • device_ifv : {type: string}
    • The identifierForVendor is an alphanumeric string that uniquely identifies a device to the app’s vendor..
  • device_screen_width : {type: integer}
    • It indicates the device screen width.
  • device_screen_height : {type: integer}
    • It indicates the device screen height.
  • device_localized_model : {type: string}
    • It indicates the localized version of model.
  • device_system_name : {type: string}
    • It indicates the user-visible operating system name string. Eg: iOS
  • device_system_version : {type: string}
    • It indicates the user-visible operating system version string. Eg: 13.3
  • mobile_carrier_name : {type: string}
    • The mobile carrier name indicates the alphabetic name of the current registered network operator.
  • mobile_iso_country_code : {type: string}
    • It indicates the ISO country code for the user’s cellular service provider..
  • mobile_network_code : {type: string}
    • It indicates the mobile network code for the user’s cellular service provider.
  • is_simulator : {type: integer}
    • It indicates if device is simulator or not.

Class diagram of iOSDeviceProperties:

3.3 AppState

The iOSAppState collects the following informations:

  • application_state : {type: string}
    • Constants that indicate the running states of an app.
      • UIApplicationStateActive -> The app is running in the foreground and currently receiving events.
      • UIApplicationStateInactive -> The app is running in the foreground but is not receiving events.
      • UIApplicationStateBackground -> The app is running in the background.
  • sdk_version : {type: string}
    • The sdk version indicates the current Sift SDK version which is used.
  • window_root_view_controller_titles : {type: array}
    • The window root class name indicates the current view controller class name from where the data are collected.
  • battery_level : {type: number}
    • The current battery level, from 0 to 1.0 and -1.0 if UIDeviceBatteryStateUnknown.
  • battery_state : {type: string}
    • It indicates the current state of battery. There are following 4 cases:
      • UIDeviceBatteryStateUnknown -> if monitoring disabled.
      • UIDeviceBatteryStateUnplugged -> on battery, discharging
      • UIDeviceBatteryStateCharging -> plugged in, less than 100%
      • UIDeviceBatteryStateFull -> plugged in, at 100%
  • device_orientation : {type: string}
    • Constants that describe the physical orientation of the device.
      • UIDeviceOrientationUnknown -> The orientation of the device cannot be determined.
      • UIDeviceOrientationPortrait -> The device is in portrait mode, with the device held upright and the Home button at the bottom.
      • UIDeviceOrientationPortraitUpsideDown -> The device is in portrait mode but upside down, with the device held upright and the Home button at the top.
      • UIDeviceOrientationLandscapeLeft -> The device is in landscape mode, with the device held upright and the Home button on the right side.
      • UIDeviceOrientationLandscapeRight -> The device is in landscape mode, with the device held upright and the Home button on the left side.
      • UIDeviceOrientationFaceUp -> The device is held parallel to the ground with the screen facing upwards.
      • UIDeviceOrientationFaceDown -> The device is held parallel to the ground with the screen facing downwards.
  • proximity_state : {type: number}
    • A Boolean value that indicates whether the proximity sensor is close to the user.
  • location : {type: dictionary}
    • The location consists of collective information of latitude, longitude, accuracy and the time at which data was collected as shown in the section 3.4. (Have data only if the sift configuration and permissions are enabled)
  • heading : {type: dictionary}
    • The heading consists of collective information of time, magnetic heading, accuracy, true heading and raw magnetic field values was collected as shown in the section 3.5.
  • network_addresses : {type: array}
    • The network addresses indicate the list of IP addresses of the current device in which the SDK is running.
  • motion : {type: array}
    • Encapsulated measurements of the attitude, rotation rate, and acceleration of a device was collected as shown in the section 3.6.
  • raw_accelerometer : {type: array}
    • Retrieve data from the onboard accelerometers of a device was collected as shown in the section 3.7.
  • raw_gyro : {type: array}
    • Retrieve data from the onboard gyroscopes value of a device was collected as shown in the section 3.8.
  • raw_magnetometer : {type: array}
    • Measurements of the Earth's magnetic field relative to the device was collected as shown in the section 3.9.

Class diagram of iOSAppState:

3.4 Location

The location consist of the following information:

  • time : {type: number}
    • It indicates the time at which the location data was collected.
  • latitude : {type: number}
    • Which indicates the latitude of the collected location.
  • longitude : {type: number}
    • Which indicates the longitude of the collected location.
  • altitude : {type: number}
    • Which indicates the altitude, measured in meters.
  • horizontal_accuracy : {type: number}
    • Indicates the radius of uncertainty for the location, measured in meters.
  • vertical_accuracy : {type: number}
    • Indicates the accuracy of the altitude value, measured in meters.
  • floor : {type: number}
    • Indicates the logical floor of the building in which the user is located..
  • speed : {type: number}
    • Indicates the accuracy of the speed value, measured in meters per second.
  • course : {type: number}
    • Indicates the accuracy of the course value, measured in degrees.

Class diagram for Location:

3.5 Heading

The azimuth (orientation) of the user’s device, relative to true or magnetic north. The heading mainly collects the following information:

  • time : {type: number}
    • It indicates the time at which this heading was determined.
  • magnetic_heading : {type: number}
    • It indicates the heading (measured in degrees) relative to magnetic north.
  • accuracy : {type: number}
    • It indicates the maximum deviation (measured in degrees) between the reported heading and the true geomagnetic heading.
  • true_heading : {type: number}
    • The heading (measured in degrees) relative to true north.
  • raw_magnetic_field_x : {type: number}
    • The geomagnetic data (measured in microteslas) for the x-axis.
  • raw_magnetic_field_y : {type: number}
    • The geomagnetic data (measured in microteslas) for the y-axis.
  • raw_magnetic_field_z : {type: number}
    • The geomagnetic data (measured in microteslas) for the z-axis

Class diagram of Heading:

3.6 DeviceMotion

The iosDeviceMotion mainly collects the following information:

  • time : {type: number}
    • It indicates the time at which this motion was determined.
  • attitude_roll : {type: double}
    • A roll is a rotation around a longitudinal axis that passes through the device from its top to bottom. The roll of the device, in radians.
  • attitude_pitch : {type: double}
    • A pitch is a rotation around a lateral axis that passes through the device from side to side. The pitch of the device, in radians.
  • attitude_yaw : {type: double}
    • A yaw is a rotation around an axis that runs vertically through the device. The yaw of the device, in radians.
  • rotation_rate_x : {type: number}
    • The rotation rate of the device for the x-axis.
  • rotation_rate_y : {type: number}
    • The rotation rate of the device for the y-axis.
  • rotation_rate_z : {type: number}
    • The rotation rate of the device for the z-axis.
  • gravity_x : {type: number}
    • The gravity acceleration vector expressed in the device's reference frame for the x-axis.
  • gravity_y : {type: number}
    • The gravity acceleration vector expressed in the device's reference frame for the y-axis.
  • gravity_z : {type: number}
    • The gravity acceleration vector expressed in the device's reference frame for the z-axis.
  • user_acceleration_x : {type: number}
    • The acceleration that the user is giving to the device for the x-axis.
  • user_acceleration_y : {type: number}
    • The acceleration that the user is giving to the device for the y-axis.
  • user_acceleration_z : {type: number}
    • The acceleration that the user is giving to the device for the z-axis.
  • magnetic_field_x : {type: number}
    • Returns the magnetic field vector with respect to the device for the x-axis.
  • magnetic_field_y : {type: number}
    • Returns the magnetic field vector with respect to the device for the y-axis.
  • magnetic_field_z : {type: number}
    • Returns the magnetic field vector with respect to the device for the z-axis.
  • magnetic_field_calibration_accuracy : {type: string}
    • It Indicates the calibration accuracy of a magnetic field estimate.

Class diagram of DeviceMotion:

3.7 DeviceAccelerometerData

The accelerometer data mainly collects the following information:

  • time : {type: number}
    • It indicates the time at which this motion was determined.
  • acceleration_x : {type: number}
    • The acceleration that the user is giving to the device for the x-axis.
  • acceleration_y : {type: number}
    • The acceleration that the user is giving to the device for the y-axis.
  • acceleration_z : {type: number}
    • The acceleration that the user is giving to the device for the z-axis.

Class diagram of DeviceAccelerometerData:

3.8 DeviceGyroData

The gyro data mainly collects the following information:

  • time : {type: number}
    • It indicates the time at which this motion was determined.
  • rotation_rate_x : {type: number}
    • The rotation rate of the device for the x-axis.
  • rotation_rate_y : {type: number}
    • The rotation rate of the device for the y-axis.
  • rotation_rate_z : {type: number}
    • The rotation rate of the device for the z-axis.

Class diagram of DeviceGyroData:

3.9 DeviceMagnetometerData

The magnetometer data mainly collects the following information:

  • time : {type: number}
    • It indicates the time at which this motion was determined.
  • magnetic_field_x : {type: number}
    • Returns the magnetic field vector with respect to the device for the x-axis.
  • magnetic_field_y : {type: number}
    • Returns the magnetic field vector with respect to the device for the y-axis.
  • magnetic_field_z : {type: number}
    • Returns the magnetic field vector with respect to the device for the z-axis.

Class diagram of DeviceMagnetometerData:

4 Modules

The SDK also has a number of classes that deal with event collecting, saving and uploading to Sift server.

4.1 Sift

This is a utility class of the sift client library which handles the application-level code for interacting with the framework for collecting, saving and uploading events. This class sets up and holds references to the event queues and event collectors, including AppStateCollector and DevicePropertiesCollector.

Configuring of the Sift iOS SDK requires passing in your account id and beacon key. For Objective C:

Sift *sift = [Sift sharedInstance];

// At minimum, you should configure these two
[sift setAccountId:@"YOUR_ACCOUNT_ID"];
[sift setBeaconKey:@"YOUR_JAVASCRIPT_SNIPPET_KEY"];

For Swift:

let sift = Sift.sharedInstance
sift().accountId = "YOUR_ACCOUNT_ID"
sift().beaconKey = "YOUR_JAVASCRIPT_SNIPPET_KEY"

Sift class provide a builder class to initialize the configuration data and variable to set value:

  • (instancetype)sharedInstance
    • It return the shared instance of Sift to initialise the RootDirPath value:
  • initWithRootDirPath(rootDirPath)
  • accountId : {type: string}
    • Your account ID; defaults to nil.
  • beaconKey : {type: string}
    • Your beacon key; defaults to nil.
  • userId : {type: string}
    • Your User ID; defaults to nil.
  • disallowCollectingLocationData : {type: boolean}
    • Whether to allow location collection; defaults to false.

This class mainly handles the following task:

  • Setting Sift Configuration.
  • Setting user Id.
  • Appends the collected event to the App State queue and Device Properties queue.
  • Collect Location and Device Motion Data.

Following are the static API to interact with SDK:

  • setAccountId(accountId)
    • It will set the accountId inside the sift instance.
  • setBeaconKey(beaconKey)
    • It will set the beaconKey inside the sift instance..
  • setUserId(userId)
    • It will set the userId inside the sift instance.
  • unsetUserId()
    • Which removes any current useId to nil
  • setDisallowCollectingLocationData(disallowCollectingLocationData)
    • Whether to allow location collection; defaults to false.
  • upload()
    • It will call the upload method with force param as NO.
  • upload(force)
    • It will upload the collects events to Sift Server. If force is YES, then won't wait for queue.readyForUpload to be true.

4.2 SiftEvent

This class is the implementation of manage Sift Events that collected from app state collector and device properties collector. SiftEvent mainly handles the following task:

  • Collect the events in proper format in dictionary and do the sanity check. So that it will easier to encode and decode the events.
  • Appends the collected event to the list request.

This class have the following methods:

  • eventWithType(type, path, fields)
    • It will the create the event with specified type.
  • isEssentiallyEqualTo(event)
    • It compare event contents except time. Its return boolean value.
  • listRequest(events)
    • Create a JSON-encoded list request object. It return as NSData.
  • appendDevicePropertiesEvent(event)
    • Which invokes the task manager to execute the append task with Device Properties queue identifier and provided event.
  • sanityCheck()
    • it return YES if event contents make sense.

4.3 SiftQueue

This class is for holding events until they are ready for upload to the sift server. Whenever an event is collected and tries to add either in the App State or Device Properties queue, it will append and upload depending on the queue's batching policy. The queue's batching policy is controlled by the queue configuration and state of the queue.

The queue configuration depends on the following factors:

  • acceptSameEventAfter : {type: long}
    • Time after which an event that is basically the same as the most recently appended event can be appended again.
  • uploadWhenMoreThan : {type: int}
    • Max queue depth before flush and upload request.
  • uploadWhenOlderThan : {type: long}
    • Max queue age before flush and upload request.

Which can be initialized through the queue config class, which provide the following methods:

  • withAcceptSameEventAfter(acceptSameEventAfter): {type: long}
  • withUploadWhenMoreThan(uploadWhenMoreThan): {type: int}
  • withUploadWhenOlderThan(uploadWhenOlderThan): {type: long}
 static const SiftQueueConfig SFIosDevicePropertiesCollectorQueueConfig = {
     .uploadWhenMoreThan = 0,
     .acceptSameEventAfter = 3600  // 1 hour
 };

The DeviceProperties queue is configured as:

  • acceptSameEventAfter: 3600 // 1 hour
  • uploadWhenMoreThan: 0

The AppState queue is configured as:

  • uploadWhenMoreThan: 32 // Unit: number of events.
  • uploadWhenOlderThan: 60 // 1 minute.

This class holds the state of the queue with the following attributes:

  • identifier : {type: string}
    • The identifier is the key for the queue.
  • queue : {type: NSMutableArray}
    • The list of collected events as of now to be uploaded depending on the policy.
  • config : {type: SiftQueueConfig}
    • The configuration of the queue which decides the batching policy.
  • lastEvent : {type: SiftEvent}
    • The recent event added to the queue.
  • lastUploadTimestamp: {type: SFTimestamp}
    • The time at which recent upload was carried on.
  • archivePath: {type: string}
    • The time at which recent upload was carried on.

This class have the following methods:

  • archive()
    • This method write the queue content to specified path in NSMutableDictionary format. This dictionary will have queue, lastEvent and lastUploadTimestamp detail.
  • unarchive()
    • This method will unarchive the content from the given path. And also assign values to queue, lastEvent and lastUploadTimestamp from unarchived dictionary detail.
  • append(event)
    • Where event is the collected event to be appended and uploaded depending on the queue batching policies.
  • transfer()
    • It will transfer ownership of the queue of events to the caller.
  • readyForUpload()
    • The queue uploading policy is based on:
      • When queue is full -> _config.uploadWhenMoreThan >= 0 && _queue.count > _config.uploadWhenMoreThan
      • When queue is old -> _config.uploadWhenOlderThan > 0 && _queue.count > 0 && now > _lastUploadTimestamp + _config.uploadWhenOlderThan * 1000
  • requestUpload()
    • This method will the upload method from sift class which is used at the time of uploading events, whenever the collected events are ready for upload

4.4 SiftUploader

This module upload the events to the Sift Server. It contains App state events and device properties events.

This class have the following methods:

  • upload(events)

    • Add the events to batches. If app is in background ithen archive the data. Later it will doUpload method which will upload the collects events to Sift Server.

  • doUpload()

    • This method will the upload events to the Sift server .

  • unarchive()

    • This method will unarchive the content from the given path. And also assign values to batches and numRejects from unarchived dictionary detail.

  • upload(events)

    • It will upload the collects events to Sift Server.

    4.5 SiftDeviceProperties

    This module collect the device proerties details and assign it to the sift event.

    This class have the following methods:

    • collect()
      • Collect device properties through its own queue.

The DeviceProperties queue is configured as:

  • acceptSameEventAfter: 3600 // 1 hour
  • uploadWhenMoreThan: 0

This class holds the device related properties with the following attributes as mentioned in section 3.2.

4.6 SiftAppState

This module collect the app state details and assign it to the sift event. App state collects the location, haeding, device motion, accelerometer data, gyro data amd magnetometer data details.

This class have the following methods:

  • archive()
    • This method write the queue content to specified path in NSMutableDictionary format. This dictionary will have bucket and lastCollectedAt details.
  • unarchive()
    • This method will unarchive the content from the given path. And also assign values to bucket and lastCollectedAt from unarchived dictionary detail.
  • updateDeviceMotion(data)
    • This method will send the CMDeviceMotion data you have got.
  • updateAccelerometerData(data)
    • This method will send the CMAccelerometerData data you have got.
  • updateGyroData(data)
    • This method will send the CMGyroData data you have got.
  • updateMagnetometerData(data)
    • This method will send the CMMagnetometerData data you have got.
  • requestCollectionWithTitle(title)
    • Request to collect app state and this mrequest might be ignored due to rate limiting.
  • checkAndCollectWhenNoneRecently(now)
    • This method will collect app state if there was no collection in the last SF_MAX_COLLECTION_PERIOD of time and app is active.
  • collectWithTitle(title, now)
    • This method will collect app state with title. Here title is String and now is SFTimestamp.
  • canCollectLocationData()
    • This method will return YES if can collect Location data.
  • disallowCollectingLocationData()
    • This method will return disallowCollectingLocationData Bool value.
  • allowUsingMotionSensors()
    • If you intend to use motion sensors occasionally, please call the following methods to send us motion data.

The AppState queue is configured as:

  • uploadWhenMoreThan: 32 // Unit: number of events.
  • uploadWhenOlderThan: 60 // 1 minute.

This class holds the application related datas with the following attributes as mentioned in section 3.3.

5 Flow Chart