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: "[e-mail]"}});

// 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'