Merge branch 'release/0.3.0'

snowplow-incubator · Jan 16, 2025 · 8e8143f · 8e8143f
2 parents 827459c + 20018be
commit 8e8143f
Show file tree

Hide file tree

Showing 10 changed files with 5,560 additions and 46 deletions.
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,3 +1,7 @@
+# 0.3.0
+
+* Integrate with new mobile interfaces (#19)
+
 # 0.2.1
 
 * Fix module resolution for first and third-party dependencies using require and import (#15)

diff --git a/README.md b/README.md
@@ -11,9 +11,9 @@ Snowplow is a scalable open-source platform for rich, high quality, low-latency
 
 ## Snowplow WebView Tracker Overview
 
-The Snowplow WebView Tracker allows you to add analytics to your Web views embedded in mobile apps when using a [Snowplow][snowplow] pipeline.
+The Snowplow WebView Tracker allows you to add analytics to your WebViews embedded in mobile apps when using a [Snowplow][snowplow] pipeline.
 
-The WebView tracker should be integrated in Web apps used in Web views within native mobile apps. The tracker provides APIs to track Snowplow events. It forwards the events to the native app code to be tracked by the Snowplow mobile trackers ([iOS][ios-tracker], [Android tracker][android-tracker], or [React Native][react-native-tracker]). The diagram below shows the interaction of the WebView and mobile trackers in hybrid apps.
+The WebView tracker should be integrated in Web apps used in WebViews within native mobile apps. The tracker provides APIs to track Snowplow events. It forwards the events to the native app code to be tracked by the Snowplow mobile trackers ([iOS][ios-tracker], [Android][android-tracker], or [React Native][react-native-tracker]). The diagram below shows the interaction of the WebView and mobile trackers in hybrid apps.
 
 ```mermaid
 flowchart TB
@@ -44,8 +44,6 @@ end
 nativeTracker -- "Sends tracked events" --> collector
 ```
 
-**Technical documentation can be found for each tracker in our [Hybrid Apps accelerator][webview-docs].**
-
 ## Quick Start
 
 ### Installation from npm
@@ -62,7 +60,7 @@ You will then be able to use the functions provided by the WebView tracker as fo
 import { trackSelfDescribingEvent } from '@snowplow/webview-tracker';
 ```
 
-In addition, you will need to install the iOS or Android tracker in your native code and configure and initialize a tracker (see the [mobile tracker docs][mobile-tracker-setup-docs]). Afterwards, you will be able to subscribe to and track the events from the WebView tracker in a Web view by calling `Snowplow.subscribeToWebViewEvents(webView)`.
+In addition, you will need to install the [iOS][ios-tracker], [Android][android-tracker], or [React Native][react-native-tracker] tracker in your native code and configure and initialize a tracker. Afterwards, you will be able to subscribe to and track the events from the WebView tracker in a WebView.
 
 ### Installation with the Snowplow tag
 
@@ -113,14 +111,14 @@ Please refer to the [tracker documentation][webview-docs] to learn more about th
 ## Find Out More
 
 | Technical Docs                        |
-|---------------------------------------|
+| ------------------------------------- |
 | [![i1][techdocs-image]][webview-docs] |
 | [Technical Docs][webview-docs]        |
 
 ## Maintainers
 
 | Contributing                                 |
-|----------------------------------------------|
+| -------------------------------------------- |
 | [![i4][contributing-image]](CONTRIBUTING.md) |
 | [Contributing](CONTRIBUTING.md)              |
 
@@ -140,12 +138,12 @@ limitations under the License.
 [website]: https://snowplow.io
 [snowplow]: https://github.com/snowplow/snowplow
 [docs]: https://docs.snowplow.io/
-[webview-docs]: https://docs.snowplow.io/docs/collecting-data/collecting-from-own-applications/webview-tracker/
-[mobile-tracker-setup-docs]: https://docs.snowplow.io/docs/collecting-data/collecting-from-own-applications/mobile-trackers/installation-and-set-up/
+[webview-docs]: https://docs.snowplow.io/docs/sources/trackers/webview-tracker/
+[mobile-tracker-setup-docs]: https://docs.snowplow.io/docs/sources/trackers/mobile-trackers/installation-and-set-up/
 
-[ios-tracker]: https://github.com/snowplow/snowplow-objc-tracker
+[ios-tracker]: https:///github.com/snowplow/snowplow-ios-tracker
 [android-tracker]: https://github.com/snowplow/snowplow-android-tracker
-[react-native-tracker]: https://docs.snowplow.io/docs/collecting-data/collecting-from-own-applications/react-native-tracker/
+[react-native-tracker]: https://github.com/snowplow/snowplow-javascript-tracker
 
 [gh-actions]: https://github.com/snowplow-incubator/snowplow-webview-tracker/actions/workflows/build.yml
 [gh-actions-image]: https://github.com/snowplow-incubator/snowplow-webview-tracker/actions/workflows/build.yml/badge.svg

diff --git a/example/src/App.js b/example/src/App.js
@@ -1,30 +1,70 @@
 import logo from './logo.svg';
 import './App.css';
-import { trackSelfDescribingEvent, trackPageView, trackScreenView, trackStructEvent } from '@snowplow/webview-tracker';
+import {
+  trackSelfDescribingEvent,
+  trackPageView,
+  trackScreenView,
+  trackStructEvent,
+  trackWebViewEvent,
+} from '@snowplow/webview-tracker';
 import { v4 as uuidv4 } from 'uuid';
 
 function trackEvents() {
-  trackSelfDescribingEvent({
-    event: {
-      schema: 'iglu:com.snowplowanalytics.snowplow/link_click/jsonschema/1-0-1',
-      data: {
-        targetUrl: 'http://a-target-url.com'
-      }
+  trackWebViewEvent(
+    {
+      properties: {
+        eventName: 'ue',
+        trackerVersion: 'webview',
+        useragent: 'useragent',
+      },
+      event: {
+        schema:
+          'iglu:com.snowplowanalytics.snowplow/button_click/jsonschema/1-0-0',
+        data: {
+          label: 'webview test',
+        },
+      },
+      context: [
+        {
+          schema:
+            'iglu:com.apple.swiftui/open_immersive_space/jsonschema/1-0-0',
+          data: {},
+        },
+      ],
     },
-    context: [
-      {
-        schema: 'iglu:com.snowplowanalytics.snowplow/link_click/jsonschema/1-0-1',
+    ['sp1']
+  );
+
+  trackSelfDescribingEvent(
+    {
+      event: {
+        schema:
+          'iglu:com.snowplowanalytics.snowplow/link_click/jsonschema/1-0-1',
         data: {
-          targetUrl: 'http://in-context.com'
-        }
-      }
-    ],
-  }, ['sp1']);
+          targetUrl: 'http://a-target-url.com',
+        },
+      },
+      context: [
+        {
+          schema:
+            'iglu:com.snowplowanalytics.snowplow/link_click/jsonschema/1-0-1',
+          data: {
+            targetUrl: 'http://in-context.com',
+          },
+        },
+      ],
+    },
+    ['sp1']
+  );
 
   trackPageView();
 
   trackStructEvent({
-    category: 'cat', action: 'act', property: 'prop', label: 'lbl', value: 10
+    category: 'cat',
+    action: 'act',
+    property: 'prop',
+    label: 'lbl',
+    value: 10,
   });
 
   trackScreenView({
@@ -43,12 +83,8 @@ function App() {
     <div className="App">
       <header className="App-header">
         <img src={logo} className="App-logo" alt="logo" />
-        <p>
-          Hello from a Webview!
-        </p>
-        <button onClick={trackEvents}>
-          Track events
-        </button>
+        <p>Hello from a Webview!</p>
+        <button onClick={trackEvents}>Track events</button>
       </header>
     </div>
   );

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@snowplow/webview-tracker",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "WebView tracker for Snowplow",
   "license": "Apache-2.0",
   "repository": {

diff --git a/src/api.ts b/src/api.ts
@@ -38,22 +38,40 @@ export interface SelfDescribingEvent {
 }
 
 /**
- * A Structured Event
- * A classic style of event tracking, allows for easier movement between analytics
- * systems. A loosely typed event, creating a Self Describing event is preferred, but
- * useful for interoperability.
+ * Event properties that are sent directly, not as part of a self-describing schema.
+ * These properties will have their own column in the warehouse event table.
  */
-export interface StructuredEvent {
-  /** Name you for the group of objects you want to track e.g. "media", "ecomm". */
-  category: string;
-  /** Defines the type of user interaction for the web object. */
-  action: string;
-  /** Identifies the specific object being actioned. */
+export interface AtomicProperties {
+  /** Type of event, e.g. "pp" for page ping. */
+  eventName?: string;
+  /** Version of the tracker used. */
+  trackerVersion?: string;
+  /** The browser useragent. */
+  useragent?: string;
+  /** For page view events. The page URL. */
+  url?: string;
+  /** For page view events. The page title. */
+  title?: string;
+  /** For page view events. The referrer URL. */
+  referrer?: string;
+  /** For structured events. Name for the group of objects you want to track. */
+  category?: string;
+  /** For structured events. Defines the type of user interaction for the web object. */
+  action?: string;
+  /** For structured events. Identifies the specific object being actioned. */
   label?: string;
-  /** Describes the object or the action performed on it. */
+  /** For structured events. Describes the object or the action performed on it. */
   property?: string;
-  /** Quantifies or further describes the user action. */
+  /** For structured events. Quantifies or further describes the user action. */
   value?: number;
+  /** For page ping events. The minimum X offset. */
+  minXOffset?: number;
+  /** For page ping events. The maximum X offset. */
+  maxXOffset?: number;
+  /** For page ping events. The minimum Y offset. */
+  minYOffset?: number;
+  /** For page ping events. The maximum Y offset. */
+  maxYOffset?: number;
 }
 
 /**
@@ -91,12 +109,36 @@ interface FullPageViewEvent extends PageViewEvent {
   referrer?: string;
 }
 
+/**
+ * A Structured Event
+ * A classic style of event tracking, allows for easier movement between analytics
+ * systems. A loosely typed event, creating a Self Describing event is preferred, but
+ * useful for interoperability.
+ */
+export interface StructuredEvent {
+  /** Name you for the group of objects you want to track e.g. "media", "ecomm". */
+  category: string;
+  /** Defines the type of user interaction for the web object. */
+  action: string;
+  /** Identifies the specific object being actioned. */
+  label?: string;
+  /** Describes the object or the action performed on it. */
+  property?: string;
+  /** Quantifies or further describes the user action. */
+  value?: number;
+}
+
 /** Additional data points to set when tracking an event */
 export interface CommonEventProperties {
   /** Add context to an event by setting an Array of Self Describing JSON */
   context?: Array<SelfDescribingJson> | null;
 }
 
+export interface WebViewEvent {
+  properties: AtomicProperties;
+  event?: SelfDescribingEvent;
+}
+
 /** Interface for communicating with the Android mobile tracker */
 export type SnowplowWebInterface = {
   trackSelfDescribingEvent: (
@@ -134,6 +176,16 @@ export type SnowplowWebInterface = {
   ) => void;
 };
 
+/** Interface for communicating with the Android mobile tracker from v6.1+ onwards */
+export type SnowplowWebInterfaceV2 = {
+  trackWebViewEvent: (
+    atomicProperties: string,
+    selfDescribingEventData?: string | null,
+    context?: string | null,
+    trackers?: Array<string> | null
+  ) => void;
+};
+
 /** Interface for communicating with the iOS mobile tracker */
 export type WebkitMessageHandler = {
   postMessage: (message: {
@@ -148,6 +200,16 @@ export type WebkitMessageHandler = {
   }) => void;
 };
 
+/** Interface for communicating with the iOS mobile tracker from v6.1+ onwards */
+export type WebkitMessageHandlerV2 = {
+  postMessage: (message: {
+    atomicProperties: string;
+    selfDescribingEventData?: string | null;
+    context?: string | null;
+    trackers?: Array<string> | null;
+  }) => void;
+};
+
 /** Interface for communicating with the React Native tracker */
 export type ReactNativeInterface = {
   postMessage: (message: string) => void;
@@ -156,9 +218,11 @@ export type ReactNativeInterface = {
 declare global {
   interface Window {
     SnowplowWebInterface?: SnowplowWebInterface;
+    SnowplowWebInterfaceV2?: SnowplowWebInterfaceV2;
     webkit?: {
       messageHandlers?: {
         snowplow?: WebkitMessageHandler;
+        snowplowV2?: WebkitMessageHandlerV2;
       };
     };
     ReactNativeWebView?: ReactNativeInterface;