JavaScript trackers 4.2 with the React Native tracker

docs/sources/trackers/javascript-trackers/web-tracker/plugins/index.md

@@ -47,6 +47,7 @@ If you are using the JavaScript tracker with the full `sp.js` and your plugin is
 | Site*                                                                                                                                                       | Events              | Manual               | ✅       | ❌            | `browser-plugin-site-tracking`                 |
 | [Timezone](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/timezone-geolocation/index.md)            | Other               | Automatic            | ❌       | ❌            | `browser-plugin-timezone`                      |
 | [Web vitals](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/web-vitals/index.md)                    | Events              | Automatic            | ✅       | ❌            | `browser-plugin-web-vitals`                    |
+| [Screen views](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/screen-views/index.md)                    | Events              | Combination            | ❌       | ❌            | `browser-plugin-screen-tracking`                    |
 
 *The site tracking plugin provides events for [site search](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/site-search/index.md), [social media interactions](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/social-media/index.md), and [timing](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/timings/generic/index.md).
 

docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/screen-views/index.md

@@ -0,0 +1,306 @@
+---
+title: "Screen views"
+sidebar_position: 60
+---
+
+# Screen view tracking
+
+```mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+```
+
+Screen view tracking is the recommended way to track users opening a screen in mobile apps.
+They are the default option for tracking views in our mobile trackers (iOS, Android, React Native, Flutter).
+On Web, [we recommend using page views](/docs/sources/trackers/javascript-trackers/web-tracker/tracking-events/page-views/index.md) to track users visiting a page.
+However, using the screen view tracking plugin is also an option on Web if you prefer this data model.
+
+:::note
+The plugin is available from Version 4.2 of the tracker.
+:::
+
+## Install plugin
+
+<Tabs groupId="platform" queryString>
+<TabItem value="js" label="JavaScript (tag)" default>
+
+| Tracker Distribution | Included |
+|----------------------|----------|
+| `sp.js`              | ✅        |
+| `sp.lite.js`         | ❌        |
+
+**Download:**
+
+<table>
+  <tbody>
+    <tr>
+      <td>Download from GitHub Releases (Recommended)</td>
+      <td>
+        <a href="https://github.com/snowplow/snowplow-javascript-tracker/releases">Github Releases (plugins.umd.zip)</a>
+      </td>
+    </tr>
+    <tr>
+      <td>Available on jsDelivr</td>
+      <td>
+        <a href="https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-screen-tracking@latest/dist/index.umd.min.js">jsDelivr</a> (latest)
+      </td>
+    </tr>
+    <tr>
+      <td>Available on unpkg</td>
+      <td>
+        <a href="https://unpkg.com/@snowplow/browser-plugin-screen-tracking@latest/dist/index.umd.min.js">unpkg</a> (latest)
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+</TabItem>
+<TabItem value="browser" label="Browser (npm)">
+
+- `npm install @snowplow/browser-plugin-screen-tracking`
+- `yarn add @snowplow/browser-plugin-screen-tracking`
+- `pnpm add @snowplow/browser-plugin-screen-tracking`
+
+</TabItem>
+</Tabs>
+
+In order to make use of the plugin, you will need to register it with the tracker:
+
+<Tabs groupId="platform" queryString>
+<TabItem value="js" label="JavaScript (tag)" default>
+
+```javascript
+window.snowplow(
+    'addPlugin',
+    'https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-button-click-tracking@latest/dist/index.umd.min.js',
+    ['snowplowScreenTrackingPlugin', 'ScreenTrackingPlugin']
+);
+```
+
+</TabItem>
+<TabItem value="browser" label="Browser (npm)">
+
+```javascript
+import { ScreenTrackingPlugin } from '@snowplow/browser-plugin-screen-tracking';
+
+newTracker('sp1', '{{collector_url}}', {
+   appId: 'my-app-id',
+   plugins: [
+    ScreenTrackingPlugin()
+   ],
+});
+```
+
+</TabItem>
+</Tabs>
+
+
+## Track a screen view event
+
+To track a screen view event, use the `trackScreenView` function.
+This will track a self-describing event with [the schema described here](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-and-screen-view-events/index.md#screen-view-events).
+
+<Tabs groupId="platform" queryString>
+<TabItem value="js" label="JavaScript (tag)" default>
+
+```javascript
+window.snowplow(
+  'trackScreenView',
+  {
+    name: 'my-screen-name',
+    id: '5d79770b-015b-4af8-8c91-b2ed6faf4b1e', // generated automatically if not provided
+    type: 'carousel', // optional
+    transitionType: 'basic', // optional
+  }
+);
+```
+
+</TabItem>
+<TabItem value="browser" label="Browser (npm)">
+
+```javascript
+import { trackScreenView } from '@snowplow/browser-plugin-screen-tracking';
+
+trackScreenView({
+  name: 'my-screen-name',
+  id: '5d79770b-015b-4af8-8c91-b2ed6faf4b1e', // generated automatically if not provided
+  type: 'carousel', // optional
+  transitionType: 'basic', // optional
+});
+```
+
+</TabItem>
+</Tabs>
+
+## Screen context entity
+
+<Tabs groupId="platform" queryString>
+<TabItem value="js" label="JavaScript (tag)" default>
+
+```javascript
+window.snowplow(
+    'addPlugin',
+    'https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-button-click-tracking@latest/dist/index.umd.min.js',
+    ['snowplowScreenTrackingPlugin', 'ScreenTrackingPlugin']
+    [
+      {
+        screenContext: true, // enabled by default
+      }
+    ]
+);
+```
+
+</TabItem>
+<TabItem value="browser" label="Browser (npm)">
+
+```javascript
+import { ScreenTrackingPlugin, trackScreenView } from '@snowplow/browser-plugin-screen-tracking';
+
+newTracker('sp1', '{{collector_url}}', {
+   appId: 'my-app-id',
+   plugins: [
+    ScreenTrackingPlugin({
+      screenContext: true, // enabled by default
+    })
+   ],
+});
+```
+
+</TabItem>
+</Tabs>
+
+If the `screenContext` property is enabled, the tracker attaches a [`Screen` entity](http://iglucentral.com/schemas/com.snowplowanalytics.mobile/screen/jsonschema/1-0-0) to all the events tracked by the tracker reporting the last (and probably current) screen visible on device when the event was tracked.
+
+The `Screen` entity is conditioned by the internal state of the tracker only. To make an example, if the developer manually tracks a `ScreenView` event, all the following events will have a `Screen` entity attached reporting the same information as the last tracked ScreenView event.
+
+## Screen engagement tracking
+
+<Tabs groupId="platform" queryString>
+<TabItem value="js" label="JavaScript (tag)" default>
+
+```javascript
+window.snowplow(
+    'addPlugin',
+    'https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-button-click-tracking@latest/dist/index.umd.min.js',
+    ['snowplowScreenTrackingPlugin', 'ScreenTrackingPlugin']
+    [
+      {
+        screenEngagementAutotracking: true, // enabled by default
+      }
+    ]
+);
+```
+
+</TabItem>
+<TabItem value="browser" label="Browser (npm)">
+
+```javascript
+import { ScreenTrackingPlugin, trackScreenView } from '@snowplow/browser-plugin-screen-tracking';
+
+newTracker('sp1', '{{collector_url}}', {
+   appId: 'my-app-id',
+   plugins: [
+    ScreenTrackingPlugin({
+      screenEngagementAutotracking: true, // enabled by default
+    })
+   ],
+});
+```
+
+</TabItem>
+</Tabs>
+
+
+Screen engagement tracking is a feature that enables tracking the user activity on the screen.
+This consists of the time spent and the amount of content viewed on the screen.
+
+Concretely, it consists of the following metrics:
+
+1. Time spent on screen while the app was in foreground (tracked automatically).
+2. Time spent on screen while the app was in background (tracked automatically).
+3. Number of list items scrolled out of all list items (requires some manual tracking).
+4. Scroll depth in pixels (requires some manual tracking).
+
+This information is attached using a [`screen_summary` context entity](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-activity-tracking/index.md#screen-summary-entity) to the following events:
+
+1. [`screen_end` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/page-activity-tracking/index.md#screen-end-event) that is automatically tracked before a new screen view event.
+2. [`application_background` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#background-event).
+3. [`application_foreground` event](/docs/sources/trackers/snowplow-tracker-protocol/ootb-data/mobile-lifecycle-events/index.md#foreground-event).
+
+Screen engagement tracking is enabled by default, but can be configured using the `screenEngagementAutotracking` option when initializing the plugin.
+
+For a demo of how mobile screen engagement tracking works in action, **[please visit this demo](https://snowplow-incubator.github.io/mobile-screen-engagement-demo/)**.
+
+#### Updating list item view and scroll depth information
+
+To update the list item viewed and scroll depth information tracked in the screen summary entity, you can track the `ListItemView` and `ScrollChanged` events with this information.
+When tracked, the tracker won't send these events individually to the collector, but will process the information into the next `screen_summary` entity and discard the events.
+You may want to track the events every time a new list item is viewed on the screen, or whenever the scroll position changes.
+
+To update the list items viewed information:
+
+<Tabs groupId="platform" queryString>
+<TabItem value="js" label="JavaScript (tag)" default>
+
+```javascript
+window.snowplow(
+  'trackListItemView',
+  {
+    index: 1,
+    itemsCount: 10,
+  }
+);
+```
+
+</TabItem>
+<TabItem value="browser" label="Browser (npm)">
+
+```javascript
+import { trackListItemView } from '@snowplow/browser-plugin-screen-tracking';
+
+trackListItemView({
+  index: 1,
+  itemsCount: 10,
+});
+```
+
+</TabItem>
+</Tabs>
+
+To update the scroll depth information:
+
+<Tabs groupId="platform" queryString>
+<TabItem value="js" label="JavaScript (tag)" default>
+
+```javascript
+window.snowplow(
+  'trackScrollChanged',
+  {
+    yOffset: 10,
+    xOffset: 20,
+    viewHeight: 100,
+    viewWidth: 200,
+    contentHeight: 300,
+    contentWidth: 400,
+  }
+);
+```
+
+</TabItem>
+<TabItem value="browser" label="Browser (npm)">
+
+```javascript
+import { trackScrollChanged } from '@snowplow/browser-plugin-screen-tracking';
+
+trackScrollChanged({
+  yOffset: 10,
+  xOffset: 20,
+  viewHeight: 100,
+  viewWidth: 200,
+  contentHeight: 300,
+  contentWidth: 400,
+});
+```
+
+</TabItem>
+</Tabs>

docs/sources/trackers/react-native-tracker/advanced-usage/index.md

@@ -6,7 +6,7 @@ sidebar_position: 40
 
 ## Removing a tracker at runtime
 
-As also mentioned in Introduction, besides the `createTracker` function, the React Native Tracker also provides two functions that allow you to remove a tracker (or all of them) at runtime.
+As also mentioned in Introduction, besides the `newTracker` function, the React Native Tracker also provides two functions that allow you to remove a tracker (or all of them) at runtime.
 
 ### removeTracker
 
@@ -15,7 +15,7 @@ As each tracker is identified by its namespace, in order to remove a tracker at
 For example, assuming an existing tracker with namespace `sp1` :
 
 ```javascript
-import { createTracker, removeTracker } from '@snowplow/react-native-tracker';
+import { newTracker, removeTracker } from '@snowplow/react-native-tracker';
 
 // ...
 
@@ -31,27 +31,3 @@ import { removeAllTrackers } from '@snowplow/react-native-tracker';
 
 removeAllTrackers();
 ```
-
-## Accessing the tracker from native code
-
-Since the Snowplow React Native Tracker is a wrapper around the native trackers for iOS and Android, it is possible to access the underlying iOS and Android trackers in native iOS and Android code. This allows you to:
-
-1. Instantiate a new tracker instance either in React Native or iOS/Android native code.
-2. Track events using the same tracker instance from both React Native code as well as iOS/Android native code.
-
-This is a better approach than creating a separate tracker instance for React Native and for native code because it enables all the events to share the same user and session identifiers.
-
-As an example, we have implemented this setup in [a simple demo app](https://github.com/snowplow-incubator/snowplow-react-native-demo-hybrid). The app does the following:
-
-1. [Adds a dependency](https://github.com/snowplow-incubator/snowplow-react-native-demo-hybrid/blob/main/package.json#L3) for the React Native tracker.
-2. [Creates a tracker instance](https://github.com/snowplow-incubator/snowplow-react-native-demo-hybrid/blob/main/App.tsx#L5) in the React Native code.
-3. [Tracks a screen view event](https://github.com/snowplow-incubator/snowplow-react-native-demo-hybrid/blob/main/App.tsx#L9) in the React Native code.
-4. [Adds the Android tracker as a dependency](https://github.com/snowplow-incubator/snowplow-react-native-demo-hybrid/blob/main/android/app/build.gradle#L182-L183) in the Android app.
-5. [Periodically tracks an event](https://github.com/snowplow-incubator/snowplow-react-native-demo-hybrid/blob/main/android/app/src/main/java/com/snowplowanalytics/reactnativedemohybrid/MainActivity.java#L29-L37) from the Android native code.
-6. [Periodically tracks an event](https://github.com/snowplow-incubator/snowplow-react-native-demo-hybrid/blob/main/ios/snowplowreactnativedemohybrid/main.m#L9-L15) from the iOS native code.
-
-When accessing the native tracker APIs in Swift, Objective-C, Java, or Kotlin, refer to the documentation for the [mobile trackers](/docs/sources/trackers/mobile-trackers/index.md).
-
-:::note
-Please note that in Android, you will need to add a dependency for the Android tracker to your `build.gradle` inside the Android codebase within your React Native app. Follow the instructions in the [mobile tracker documentation](/docs/sources/trackers/mobile-trackers/index.md). Make sure that you include the same version of the Android tracker as used by the React Native tracker.
-:::