ci-trap-capacitor

Capacitor plugin wrapper over the Android and IOS Trap libraries.

Install

npm install ci-trap-capacitor
npx cap sync

Example

With the following code snippets you are able to configure, start, manage and stop the data collection.

Platform specific notes

• Android: There is no need for additional config or user permission to capture data with the specified config (see below).

• IOS: The only requirement is to have the bundle record NSMotionUsageDescription defined and filled in to collect Accelerometer, Gravity, Gyroscope and Magnetometer data.

Please note that enabling Bluetooth, GPS and WiFi related features might need additional permissions.

Sample code

// Initialze Trap with the specified config. This should be called only once
const config = new TrapConfig();
config.reporter.url = "https://[SERVER_URL]/api/1/submit/{sessionId}/{streamId}"
config.defaultDataCollection.collectors = [
  CollectorTypes.Accelerometer,
  CollectorTypes.Battery,
  CollectorTypes.Gravity,
  CollectorTypes.Gyroscope,
  CollectorTypes.Magnetometer,
  CollectorTypes.Metadata,
  CollectorTypes.Pointer,
  CollectorTypes.Stylus,
  CollectorTypes.Touch,
];
// Use the same config in every scenario
config.lowBatteryDataCollection = config.defaultDataCollection;
config.lowDataDataCollection = config.defaultDataCollection;
await CapacitorTrap.configure({config});

// Specify the userId as custom metadata. It will be active until it is removed
// explicitly or a new value is set.
await CapacitorTrap.addCustomMetadata(
  { key: "userId", value: { type: "email", value: "[email protected]"}});

// Starts the data collection
await CapacitorTrap.start();

// Add any custom event, that will be added to the event stream once,
// immediately when the method is called
await CapacitorTrap.addCustomEvent({ event: {
  action: 'gameStarted',
  game: 'memory'
}});

// Removes the userId as custom metadata (e.g. user logged out)
await CapacitorTrap.removeCustomMetadata({ key: "userId" });

// Stops the data collection
await CapacitorTrap.stop();

API

• addCustomEvent(...)
• addCustomMetadata(...)
• checkPermission(...)
• configure(...)
• cleanUp()
• removeCustomMetadata(...)
• requestPermission(...)
• start()
• stop()
• Interfaces
• Enums

addCustomEvent(...)

addCustomEvent(options: { event: any; }) => Promise<void>

Add custom event

| Param | Type | | ------------- | ---------------------------- | | options | { event: any; } |

addCustomMetadata(...)

addCustomMetadata(options: { key: string; value: any; }) => Promise<void>

Add custom metadata

| Param | Type | | ------------- | ----------------------------------------- | | options | { key: string; value: any; } |

checkPermission(...)

checkPermission(options: { collector: CollectorTypes; }) => Promise<PermissionResult>

Checks permission for the specific collector. Returns true if the collector has the required permission.

| Param | Type | | ------------- | ------------------------------------------------------------------------- | | options | { collector: CollectorTypes; } |

Returns: Promise<PermissionResult>

configure(...)

configure(options: { config: TrapConfigurationType; }) => Promise<void>

Initialize the plugin

| Param | Type | | ------------- | ------------------------------------------------------------------------------------ | | options | { config: TrapConfigurationType; } |

cleanUp()

cleanUp() => Promise<void>

Cleans up the plugin

removeCustomMetadata(...)

removeCustomMetadata(options: { key: string; }) => Promise<void>

Remove custom metadata

| Param | Type | | ------------- | ----------------------------- | | options | { key: string; } |

requestPermission(...)

requestPermission(options: { collector: CollectorTypes; }) => Promise<void>

Request permission for the specific collector.

| Param | Type | | ------------- | ------------------------------------------------------------------------- | | options | { collector: CollectorTypes; } |

start()

start() => Promise<void>

Start data collection

stop()

stop() => Promise<void>

Stop data collection

Interfaces

PermissionResult

| Prop | Type | | ------------ | -------------------- | | result | boolean |

TrapConfigurationType

| Prop | Type | Description | | ------------------------------ | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | defaultDataCollection | DataCollectionConfigurationType | Default data collection options. | | lowBatteryDataCollection | DataCollectionConfigurationType | Limited data collection in case of low battery | | lowDataDataCollection | DataCollectionConfigurationType | Limited data collection in case of low battery | | lowBatteryThreshold | number | Battery charge threshold for low battery status | | queueSize | number | The size of the circular data queue. | | reporter | ReporterConfigurationType | The configuration for the reporter task. | | sessionIdFilter | string | SessionId filter, if specified the data collection is only enabled if sessionId <= sessionIdFilter |

DataCollectionConfigurationType

| Prop | Type | Description | | ------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------- | | accelerationMaxReportLatencyMs | number | How long the sensor can cache reported events. | | accelerationSamplingPeriodMs | number | How frequent the sampling of the given sensor should be. | | collectCoalescedPointerEvents | boolean | Collect coalesced pointer events | | collectCoalescedStylusEvents | boolean | Collect coalesced stylus events | | collectCoalescedTouchEvents | boolean | Collect coalesced touch events | | collectors | CollectorTypes[] | The list of collectors to start at initialization. | | gravityMaxReportLatencyMs | number | How long the sensor can cache reported events. | | gravitySamplingPeriodMs | number | How frequent the sampling of the given sensor should be. | | gyroscopeMaxReportLatencyMs | number | How long the sensor can cache reported events. | | gyroscopeSamplingPeriodMs | number | How frequent the sampling of the given sensor should be. | | magnetometerMaxReportLatencyMs | number | How long the sensor can cache reported events. | | magnetometerSamplingPeriodMs | number | How frequent the sampling of the given sensor should be. | | maxNumberOfLogMessagesPerMinute | number | Maximum number of log messages per collector if the collector uses log throttling | | metadataSubmissionInterval | number | The time interval metadata events are reported. | | useGestureRecognizer | boolean | Use gesture recognizer for touch event collection |

ReporterConfigurationType

| Prop | Type | Description | | ---------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | apiKeyName | string | Name of the api key sent in the HTTP header | | apiKeyValue | string | Value of the api key sent in the HTTP header | | bufferSizeLimit | number | null | Default maximum buffer size in number of events (in web collector) | | bufferTimeout | number | null | Default timeout for sending the buffer automatically in milliseconds (in the web collector) | | cachedTransport | boolean | Whether to cache data packets on the device when connection to the remote server cannot be established. | | compress | boolean | Whether to compress the data sent to the server. If true GZIP compression is used. | | connectTimeout | number | The connect timeout for the HTTP transport in milliseconds. | | idleTimeout | number | null | Default idle timeout in milliseconds (in the web collector). | | interval | number | The time interval the reporter task runs with. | | maxFileCacheSize | number | About how much space on the device can be used to store unsent data packets. The lib might use a little more space than this value in case the data packet size exceeds the remaining space. | | readTimeout | number | The read timeout for the HTTP transport in milliseconds. | | sessionId | string | The persistent session id to send in the header frame. Must be set manually with a custom config class! | | url | string | The URL to send the data packets to. |

Enums

CollectorTypes

| Members | Value | | --------------------- | ------------------------------ | | Accelerometer | 'Accelerometer' | | Battery | 'Battery' | | Bluetooth | 'Bluetooth' | | CoarseLocation | 'CoarseLocation' | | Gravity | 'Gravity' | | Gyroscope | 'Gyroscope' | | Magnetometer | 'Magnetometer' | | Metadata | 'Metadata' | | Pointer | 'Pointer' | | PreciseLocation | 'PreciseLocation' | | Stylus | 'Stylus' | | Touch | 'Touch' | | WiFi | 'WiFi' |