Add new tracker for React Native (#1371)

.github/workflows/change_check.yml

@@ -50,6 +50,10 @@ jobs:
         working-directory: ./trackers/node-tracker
         run: api-extractor run
 
+      - name: Check for API changes to @snowplow/react-native-tracker
+        working-directory: ./trackers/react-native-tracker
+        run: api-extractor run
+
       - name: Check bundle size using bundlemon
         run: npx [email protected]
         env:

.github/workflows/publish.yml

@@ -75,10 +75,17 @@ jobs:
           api-extractor run
           api-documenter markdown --input-folder temp --output-folder ../../api-docs/docs/node-tracker/markdown
 
+      - name: Create API documentation for @snowplow/react-native-tracker
+        working-directory: ./trackers/react-native-tracker
+        run: |
+          api-extractor run
+          api-documenter markdown --input-folder temp --output-folder ../../api-docs/docs/node-tracker/markdown
+
       - name: Apply API documentation updates
         run: |
           git add api-docs/docs/browser-tracker
           git add api-docs/docs/node-tracker
+          git add api-docs/docs/react-native-tracker
           git commit --no-verify --allow-empty -m "Applying documentation updates."
           git push
 

.github/workflows/publish_prerelease.yml

@@ -75,6 +75,12 @@ jobs:
           api-extractor run
           api-documenter markdown --input-folder temp --output-folder docs/markdown
 
+      - name: Create API documentation for @snowplow/react-native-tracker
+        working-directory: ./trackers/react-native-tracker
+        run: |
+          api-extractor run
+          api-documenter markdown --input-folder temp --output-folder docs/markdown
+
       - name: Rush Publish
         run: node common/scripts/install-run-rush.js publish --apply --include-all --publish --tag next --set-access-level public --ignore-git-hooks
 

.gitignore

@@ -67,6 +67,7 @@ common/autoinstallers/*/.npmrc
 # API Extractor
 trackers/browser-tracker/temp/
 trackers/node-tracker/temp/
+trackers/react-native-tracker/temp/
 
 # Distribution files
 dist
@@ -80,4 +81,4 @@ trackers/javascript-tracker/test/local/serve/
 .DS_Store
 
 # gitleaks file
-findings.json
+findings.json

api-docs/docs/browser-tracker/browser-tracker.api.md

@@ -170,6 +170,7 @@ export interface CorePlugin {
     afterTrack?: (payload: Payload) => void;
     beforeTrack?: (payloadBuilder: PayloadBuilder) => void;
     contexts?: () => SelfDescribingJson[];
+    deactivatePlugin?: (core: TrackerCore) => void;
     filter?: (payload: Payload) => boolean;
     logger?: (logger: Logger) => void;
 }
@@ -545,6 +546,7 @@ export interface TrackerCore {
     addPayloadPair: (key: string, value: unknown) => void;
     addPlugin(configuration: CorePluginConfiguration): void;
     clearGlobalContexts(): void;
+    deactivate(): void;
     getBase64Encoding(): boolean;
     removeGlobalContexts(contexts: Array<ConditionalContextProvider | ContextPrimitive | string>): void;
     resetPayloadPairs(dict: Payload): void;

api-docs/docs/browser-tracker/markdown/browser-tracker.coreplugin.deactivateplugin.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@snowplow/browser-tracker](./browser-tracker.md) &gt; [CorePlugin](./browser-tracker.coreplugin.md) &gt; [deactivatePlugin](./browser-tracker.coreplugin.deactivateplugin.md)
+
+## CorePlugin.deactivatePlugin property
+
+Called when the tracker is being destroyed. Should be used to clean up any resources or listeners that the plugin has created.
+
+<b>Signature:</b>
+
+```typescript
+deactivatePlugin?: (core: TrackerCore) => void;
+```

api-docs/docs/browser-tracker/markdown/browser-tracker.coreplugin.md

@@ -20,6 +20,7 @@ interface CorePlugin
 |  [afterTrack?](./browser-tracker.coreplugin.aftertrack.md) | (payload: Payload) =&gt; void | <i>(Optional)</i> Called just after the trackerCore callback fires |
 |  [beforeTrack?](./browser-tracker.coreplugin.beforetrack.md) | (payloadBuilder: PayloadBuilder) =&gt; void | <i>(Optional)</i> Called before the <code>filter</code> method is called and before the trackerCore callback fires (if the filter passes) |
 |  [contexts?](./browser-tracker.coreplugin.contexts.md) | () =&gt; SelfDescribingJson\[\] | <i>(Optional)</i> Called when constructing the context for each event Useful for adding additional context to events |
+|  [deactivatePlugin?](./browser-tracker.coreplugin.deactivateplugin.md) | (core: TrackerCore) =&gt; void | <i>(Optional)</i> Called when the tracker is being destroyed. Should be used to clean up any resources or listeners that the plugin has created. |
 |  [filter?](./browser-tracker.coreplugin.filter.md) | (payload: Payload) =&gt; boolean | <i>(Optional)</i> Called before the payload is sent to the callback to decide whether to send the payload or skip it |
 |  [logger?](./browser-tracker.coreplugin.logger.md) | (logger: Logger) =&gt; void | <i>(Optional)</i> Passed a logger instance which can be used to send log information to the active logger |
 

api-docs/docs/browser-tracker/markdown/browser-tracker.trackerconfiguration.md

@@ -44,6 +44,5 @@ newTracker('sp1', 'collector.my-website.com', {
  plugins: [ PerformanceTimingPlugin(), AdTrackingPlugin() ],
  stateStorageStrategy: 'cookieAndLocalStorage'
 });
-
 ```
 

api-docs/docs/browser-tracker/markdown/browser-tracker.trackercore.deactivate.md

@@ -0,0 +1,17 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@snowplow/browser-tracker](./browser-tracker.md) &gt; [TrackerCore](./browser-tracker.trackercore.md) &gt; [deactivate](./browser-tracker.trackercore.deactivate.md)
+
+## TrackerCore.deactivate() method
+
+Deactivate tracker core including all plugins. This is useful for cleaning up resources or listeners that have been created. Once deactivated, the tracker won't be able to track any events.
+
+<b>Signature:</b>
+
+```typescript
+deactivate(): void;
+```
+<b>Returns:</b>
+
+void
+

api-docs/docs/browser-tracker/markdown/browser-tracker.trackercore.md

@@ -27,6 +27,7 @@ interface TrackerCore
 |  [addPayloadDict(dict)](./browser-tracker.trackercore.addpayloaddict.md) | Merges a dictionary into payloadPairs |
 |  [addPlugin(configuration)](./browser-tracker.trackercore.addplugin.md) | Add a plugin into the plugin collection after Core has already been initialised |
 |  [clearGlobalContexts()](./browser-tracker.trackercore.clearglobalcontexts.md) | Removes all global contexts |
+|  [deactivate()](./browser-tracker.trackercore.deactivate.md) | Deactivate tracker core including all plugins. This is useful for cleaning up resources or listeners that have been created. Once deactivated, the tracker won't be able to track any events. |
 |  [getBase64Encoding()](./browser-tracker.trackercore.getbase64encoding.md) | Get current base64 encoding state |
 |  [removeGlobalContexts(contexts)](./browser-tracker.trackercore.removeglobalcontexts.md) | Removes previously added global context, performs a deep comparison of the contexts or conditional contexts |
 |  [resetPayloadPairs(dict)](./browser-tracker.trackercore.resetpayloadpairs.md) | Replace payloadPairs with a new dictionary |

api-docs/docs/node-tracker/markdown/node-tracker.coreplugin.deactivateplugin.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@snowplow/node-tracker](./node-tracker.md) &gt; [CorePlugin](./node-tracker.coreplugin.md) &gt; [deactivatePlugin](./node-tracker.coreplugin.deactivateplugin.md)
+
+## CorePlugin.deactivatePlugin property
+
+Called when the tracker is being destroyed. Should be used to clean up any resources or listeners that the plugin has created.
+
+<b>Signature:</b>
+
+```typescript
+deactivatePlugin?: (core: TrackerCore) => void;
+```

api-docs/docs/node-tracker/markdown/node-tracker.coreplugin.md

@@ -20,6 +20,7 @@ interface CorePlugin
 |  [afterTrack?](./node-tracker.coreplugin.aftertrack.md) | (payload: Payload) =&gt; void | <i>(Optional)</i> Called just after the trackerCore callback fires |
 |  [beforeTrack?](./node-tracker.coreplugin.beforetrack.md) | (payloadBuilder: PayloadBuilder) =&gt; void | <i>(Optional)</i> Called before the <code>filter</code> method is called and before the trackerCore callback fires (if the filter passes) |
 |  [contexts?](./node-tracker.coreplugin.contexts.md) | () =&gt; SelfDescribingJson\[\] | <i>(Optional)</i> Called when constructing the context for each event Useful for adding additional context to events |
+|  [deactivatePlugin?](./node-tracker.coreplugin.deactivateplugin.md) | (core: TrackerCore) =&gt; void | <i>(Optional)</i> Called when the tracker is being destroyed. Should be used to clean up any resources or listeners that the plugin has created. |
 |  [filter?](./node-tracker.coreplugin.filter.md) | (payload: Payload) =&gt; boolean | <i>(Optional)</i> Called before the payload is sent to the callback to decide whether to send the payload or skip it |
 |  [logger?](./node-tracker.coreplugin.logger.md) | (logger: Logger) =&gt; void | <i>(Optional)</i> Passed a logger instance which can be used to send log information to the active logger |
 

api-docs/docs/node-tracker/markdown/node-tracker.trackercore.deactivate.md

@@ -0,0 +1,17 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@snowplow/node-tracker](./node-tracker.md) &gt; [TrackerCore](./node-tracker.trackercore.md) &gt; [deactivate](./node-tracker.trackercore.deactivate.md)
+
+## TrackerCore.deactivate() method
+
+Deactivate tracker core including all plugins. This is useful for cleaning up resources or listeners that have been created. Once deactivated, the tracker won't be able to track any events.
+
+<b>Signature:</b>
+
+```typescript
+deactivate(): void;
+```
+<b>Returns:</b>
+
+void
+

api-docs/docs/node-tracker/markdown/node-tracker.trackercore.md

@@ -27,6 +27,7 @@ interface TrackerCore
 |  [addPayloadDict(dict)](./node-tracker.trackercore.addpayloaddict.md) | Merges a dictionary into payloadPairs |
 |  [addPlugin(configuration)](./node-tracker.trackercore.addplugin.md) | Add a plugin into the plugin collection after Core has already been initialised |
 |  [clearGlobalContexts()](./node-tracker.trackercore.clearglobalcontexts.md) | Removes all global contexts |
+|  [deactivate()](./node-tracker.trackercore.deactivate.md) | Deactivate tracker core including all plugins. This is useful for cleaning up resources or listeners that have been created. Once deactivated, the tracker won't be able to track any events. |
 |  [getBase64Encoding()](./node-tracker.trackercore.getbase64encoding.md) | Get current base64 encoding state |
 |  [removeGlobalContexts(contexts)](./node-tracker.trackercore.removeglobalcontexts.md) | Removes previously added global context, performs a deep comparison of the contexts or conditional contexts |
 |  [resetPayloadPairs(dict)](./node-tracker.trackercore.resetpayloadpairs.md) | Replace payloadPairs with a new dictionary |

api-docs/docs/node-tracker/node-tracker.api.md

@@ -165,6 +165,7 @@ export interface CorePlugin {
     afterTrack?: (payload: Payload) => void;
     beforeTrack?: (payloadBuilder: PayloadBuilder) => void;
     contexts?: () => SelfDescribingJson[];
+    deactivatePlugin?: (core: TrackerCore) => void;
     filter?: (payload: Payload) => boolean;
     logger?: (logger: Logger) => void;
 }
@@ -527,6 +528,7 @@ export interface TrackerCore {
     addPayloadPair: (key: string, value: unknown) => void;
     addPlugin(configuration: CorePluginConfiguration): void;
     clearGlobalContexts(): void;
+    deactivate(): void;
     getBase64Encoding(): boolean;
     removeGlobalContexts(contexts: Array<ConditionalContextProvider | ContextPrimitive | string>): void;
     resetPayloadPairs(dict: Payload): void;

api-docs/docs/react-native-tracker/markdown/index.md

@@ -0,0 +1,12 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md)
+
+## API Reference
+
+## Packages
+
+|  Package | Description |
+|  --- | --- |
+|  [@snowplow/react-native-tracker](./react-native-tracker.md) |  |
+

api-docs/docs/react-native-tracker/markdown/react-native-tracker.conditionalcontextprovider.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@snowplow/react-native-tracker](./react-native-tracker.md) &gt; [ConditionalContextProvider](./react-native-tracker.conditionalcontextprovider.md)
+
+## ConditionalContextProvider type
+
+Conditional context providers are two element arrays used to decide when to attach contexts, where: - the first element is some conditional criterion - the second element is any number of context primitives
+
+<b>Signature:</b>
+
+```typescript
+type ConditionalContextProvider = FilterProvider | RuleSetProvider;
+```

api-docs/docs/react-native-tracker/markdown/react-native-tracker.contextfilter.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@snowplow/react-native-tracker](./react-native-tracker.md) &gt; [ContextFilter](./react-native-tracker.contextfilter.md)
+
+## ContextFilter type
+
+A context filter is a user-supplied callback that is evaluated for each event to determine if the context associated with the filter should be attached to the event
+
+<b>Signature:</b>
+
+```typescript
+type ContextFilter = (args?: ContextEvent) => boolean;
+```

api-docs/docs/react-native-tracker/markdown/react-native-tracker.contextgenerator.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@snowplow/react-native-tracker](./react-native-tracker.md) &gt; [ContextGenerator](./react-native-tracker.contextgenerator.md)
+
+## ContextGenerator type
+
+A context generator is a user-supplied callback that is evaluated for each event to allow an additional context to be dynamically attached to the event
+
+<b>Signature:</b>
+
+```typescript
+type ContextGenerator = (args?: ContextEvent) => SelfDescribingJson | SelfDescribingJson[] | undefined;
+```

api-docs/docs/react-native-tracker/markdown/react-native-tracker.contextprimitive.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@snowplow/react-native-tracker](./react-native-tracker.md) &gt; [ContextPrimitive](./react-native-tracker.contextprimitive.md)
+
+## ContextPrimitive type
+
+A context primitive is either a self-describing JSON or a context generator
+
+<b>Signature:</b>
+
+```typescript
+type ContextPrimitive = SelfDescribingJson | ContextGenerator;
+```

api-docs/docs/react-native-tracker/markdown/react-native-tracker.coreconfiguration.base64.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@snowplow/react-native-tracker](./react-native-tracker.md) &gt; [CoreConfiguration](./react-native-tracker.coreconfiguration.md) &gt; [base64](./react-native-tracker.coreconfiguration.base64.md)
+
+## CoreConfiguration.base64 property
+
+<b>Signature:</b>
+
+```typescript
+base64?: boolean;
+```

api-docs/docs/react-native-tracker/markdown/react-native-tracker.coreconfiguration.callback.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@snowplow/react-native-tracker](./react-native-tracker.md) &gt; [CoreConfiguration](./react-native-tracker.coreconfiguration.md) &gt; [callback](./react-native-tracker.coreconfiguration.callback.md)
+
+## CoreConfiguration.callback property
+
+<b>Signature:</b>
+
+```typescript
+callback?: (PayloadData: PayloadBuilder) => void;
+```

api-docs/docs/react-native-tracker/markdown/react-native-tracker.coreconfiguration.coreplugins.md

@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@snowplow/react-native-tracker](./react-native-tracker.md) &gt; [CoreConfiguration](./react-native-tracker.coreconfiguration.md) &gt; [corePlugins](./react-native-tracker.coreconfiguration.coreplugins.md)
+
+## CoreConfiguration.corePlugins property
+
+<b>Signature:</b>
+
+```typescript
+corePlugins?: Array<CorePlugin>;
+```

api-docs/docs/react-native-tracker/markdown/react-native-tracker.coreconfiguration.md

@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@snowplow/react-native-tracker](./react-native-tracker.md) &gt; [CoreConfiguration](./react-native-tracker.coreconfiguration.md)
+
+## CoreConfiguration interface
+
+The configuration object for the tracker core library
+
+<b>Signature:</b>
+
+```typescript
+interface CoreConfiguration 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [base64?](./react-native-tracker.coreconfiguration.base64.md) | boolean | <i>(Optional)</i> |
+|  [callback?](./react-native-tracker.coreconfiguration.callback.md) | (PayloadData: PayloadBuilder) =&gt; void | <i>(Optional)</i> |
+|  [corePlugins?](./react-native-tracker.coreconfiguration.coreplugins.md) | Array&lt;CorePlugin&gt; | <i>(Optional)</i> |
+

api-docs/docs/react-native-tracker/markdown/react-native-tracker.coreplugin.activatecoreplugin.md

@@ -0,0 +1,18 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@snowplow/react-native-tracker](./react-native-tracker.md) &gt; [CorePlugin](./react-native-tracker.coreplugin.md) &gt; [activateCorePlugin](./react-native-tracker.coreplugin.activatecoreplugin.md)
+
+## CorePlugin.activateCorePlugin property
+
+Called when the plugin is initialised during the trackerCore construction
+
+<b>Signature:</b>
+
+```typescript
+activateCorePlugin?: (core: TrackerCore) => void;
+```
+
+## Remarks
+
+Use to capture the specific core instance for each instance of a core plugin
+

api-docs/docs/react-native-tracker/markdown/react-native-tracker.coreplugin.aftertrack.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@snowplow/react-native-tracker](./react-native-tracker.md) &gt; [CorePlugin](./react-native-tracker.coreplugin.md) &gt; [afterTrack](./react-native-tracker.coreplugin.aftertrack.md)
+
+## CorePlugin.afterTrack property
+
+Called just after the trackerCore callback fires
+
+<b>Signature:</b>
+
+```typescript
+afterTrack?: (payload: Payload) => void;
+```

api-docs/docs/react-native-tracker/markdown/react-native-tracker.coreplugin.beforetrack.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@snowplow/react-native-tracker](./react-native-tracker.md) &gt; [CorePlugin](./react-native-tracker.coreplugin.md) &gt; [beforeTrack](./react-native-tracker.coreplugin.beforetrack.md)
+
+## CorePlugin.beforeTrack property
+
+Called before the `filter` method is called and before the trackerCore callback fires (if the filter passes)
+
+<b>Signature:</b>
+
+```typescript
+beforeTrack?: (payloadBuilder: PayloadBuilder) => void;
+```

api-docs/docs/react-native-tracker/markdown/react-native-tracker.coreplugin.contexts.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@snowplow/react-native-tracker](./react-native-tracker.md) &gt; [CorePlugin](./react-native-tracker.coreplugin.md) &gt; [contexts](./react-native-tracker.coreplugin.contexts.md)
+
+## CorePlugin.contexts property
+
+Called when constructing the context for each event Useful for adding additional context to events
+
+<b>Signature:</b>
+
+```typescript
+contexts?: () => SelfDescribingJson[];
+```

api-docs/docs/react-native-tracker/markdown/react-native-tracker.coreplugin.deactivateplugin.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@snowplow/react-native-tracker](./react-native-tracker.md) &gt; [CorePlugin](./react-native-tracker.coreplugin.md) &gt; [deactivatePlugin](./react-native-tracker.coreplugin.deactivateplugin.md)
+
+## CorePlugin.deactivatePlugin property
+
+Called when the tracker is being destroyed. Should be used to clean up any resources or listeners that the plugin has created.
+
+<b>Signature:</b>
+
+```typescript
+deactivatePlugin?: (core: TrackerCore) => void;
+```