@uptick-ads/react-native-web-sdk 0.2.0

package/LICENSE

@@ -0,0 +1,27 @@
+# Uptick React Native Web SDK License Agreement
+
+By using or integrating the Uptick React Native Web SDK, you agree to the following terms:
+
+1. **Grant of License**
+   Uptick grants you a non-exclusive, non-transferable, revocable license to use the Uptick React Native Web SDK solely for the purpose of integrating it into your applications and products.
+
+2. **Restrictions**
+   - You may not reverse engineer, decompile, disassemble, or otherwise attempt to discover the source code of the Uptick React Native Web SDK.
+   - You may not modify, adapt, or create derivative works from the Uptick React Native Web SDK.
+   - Redistribution of the Uptick React Native Web SDK is permitted only as part of your integrated application.
+
+3. **Intellectual Property**
+   All rights, title, and interest in and to the Uptick React Native Web SDK, including any updates, modifications, and enhancements, remain with Uptick.
+
+4. **Disclaimer of Warranties**
+   The Uptick React Native Web SDK is provided "as is," without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement.
+
+5. **Limitation of Liability**
+   In no event shall Uptick be liable for any claim, damages, or other liability arising from the use of the Uptick React Native Web SDK.
+
+6. **Termination**
+   Uptick may terminate this license at any time if you violate its terms.
+
+---
+
+© 2024 Uptick. All rights reserved.

package/README.md

@@ -0,0 +1,92 @@
+# Uptick React Native Web SDK
+
+Runs the Uptick web SDK inside a `react-native-webview`, so a React Native app can show offers without a native SDK.
+One component, `UptickFlow`, with the same parameters as the [web integration](https://docs.uptick.com/publishers/web).
+
+## Requirements
+
+- React Native 0.73 or newer
+- `react-native-webview` 13.10 or newer (the component relies on `onOpenWindow`)
+- An Uptick integration id and a placement configured for your account
+
+## Installation
+
+```
+npm install @uptick-ads/react-native-web-sdk react-native-webview
+```
+
+Expo apps: `npx expo install react-native-webview`, then install this package as above.
+
+## Usage
+
+Mount `UptickFlow` where an inline offer should appear, in the flow of the screen. Pass the same parameters you would pass to the web SDK.
+
+```jsx
+import { UptickFlow } from "@uptick-ads/react-native-web-sdk";
+
+<UptickFlow
+  integrationId="AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE"
+  placement="order_confirmation"
+  first_name="Reggie"
+  total_price="$49.99"
+  shipping_price="$9.99"
+  order_id="12345"
+  customer_id="cust_12345"
+  callback={(event, data) => console.log(event, data)}
+/>
+```
+
+Whether the offer renders inline or as a popup is configured by the Uptick offers team on your placement, not in your app.
+When the placement is inline, the component sizes itself to the offer and starts at zero height, so nothing shows until an offer is ready.
+When the placement is a popup, the component presents a modal over the whole screen with a scrim and a centred card, from wherever it is mounted. Tap outside, the card's close button, and the Android back button all dismiss it.
+Because both presentations work from the same mount point, Uptick can switch a placement between inline and popup without a change to your app.
+
+## Props
+
+| Prop | Default | Purpose |
+| --- | --- | --- |
+| `integrationId` | required | Your integration's public id |
+| `placement` | `order_confirmation` | `checkout`, `order_confirmation` or `order_status` |
+| `callback` | | `(event, data)`, the same events as the web SDK callback |
+| `openUrl` | `Linking.openURL` | How accepted offers open; supply your own to use an in-app browser |
+| `style` | | Style for the inline slot |
+| `modal` | | `{ scrimColor, cardStyle, insets, maxCardHeight }` for the popup presentation |
+| `webViewProps` | | Extra props passed through to `WebView` |
+| `host` | `api.uptick.com` | API host, only for testing against other environments |
+
+### Flow parameters
+
+Passed as flat props, named as in the web integration. All values are strings.
+
+- **Site**: `site_id`
+- **User**: `customer_id`, `first_name`, `locale`
+- **Order**: `order_id`, `order_name`, `payment_method`, `currency`, `total_price`, `shipping_price`, `discount`, `zip`, `province`, `country_code`
+
+They travel in the URL fragment, which is never sent to a server, so they do not appear in request logs. Props outside this list are not forwarded.
+
+### Events
+
+`callback` receives the web SDK's lifecycle events with the same names and payloads: `init`, `flow_initialized`, `flow_delayed`, `offer_requested`, `offer_viewed`, `offer_accepted`, `offer_rejected`, `flow_complete`, plus `flow_hidden` when the user closes the offer.
+The component adds `render_type` (`{ rendered: "inline" | "popup" }`) once the first offer renders, `popup_dismissed`, `webview_error`, `webview_http_error` and `open_url_failed`.
+
+## How click-out works
+
+When a user accepts an offer the SDK opens the advertiser link with `window.open`. The component receives that through `onOpenWindow`, hands the URL to `openUrl`, and the page inside the WebView stays put, so the SDK moves on to the next offer while the user is in the browser. Do not set `setSupportMultipleWindows={false}` through `webViewProps`: on Android that makes the WebView start the navigation itself and leaves the offer frozen.
+
+## Demo
+
+`uptick-ads/uptick-react-native-web` is an Expo app that exercises inline and popup placements against a local or hosted Uptick API.
+
+## License
+
+See `LICENSE`.
+
+## Releasing
+
+Bump `version` in `package.json` and the changelog, merge to `main`, then push a matching tag:
+
+```
+git tag v0.2.1 && git push origin v0.2.1
+```
+
+The Release workflow publishes to npm with provenance and creates the GitHub release.

package/index.d.ts

@@ -0,0 +1,46 @@
+import type { ComponentProps } from "react";
+import type { StyleProp, ViewStyle } from "react-native";
+import type { WebView } from "react-native-webview";
+
+/** Flow parameters, named exactly as in the web integration (docs.uptick.com/publishers/web). All values are strings. */
+export interface UptickFlowParams {
+  site_id?: string;
+  customer_id?: string;
+  first_name?: string;
+  locale?: string;
+  order_id?: string;
+  order_name?: string;
+  payment_method?: string;
+  currency?: string;
+  total_price?: string;
+  shipping_price?: string;
+  discount?: string;
+  zip?: string;
+  province?: string;
+  country_code?: string;
+}
+
+export interface UptickModalOptions {
+  scrimColor?: string;
+  cardStyle?: StyleProp<ViewStyle>;
+  insets?: { top: number; bottom: number };
+  maxCardHeight?: number;
+}
+
+export interface UptickFlowProps extends UptickFlowParams {
+  integrationId: string;
+  placement?: string;
+  callback?: (event: string, data: unknown) => void;
+  openUrl?: (url: string) => void | Promise<unknown>;
+  style?: StyleProp<ViewStyle>;
+  modal?: UptickModalOptions;
+  webViewProps?: Partial<ComponentProps<typeof WebView>>;
+  host?: string;
+}
+
+export function UptickFlow(props: UptickFlowProps): JSX.Element;
+
+export const FLOW_PARAMS: ReadonlyArray<keyof UptickFlowParams>;
+export function pickFlowParams(props: Record<string, unknown>): UptickFlowParams;
+export function buildEmbedUrl(options: { host: string; integrationId: string; placement?: string; params?: UptickFlowParams }): string;
+export function embedPath(host: string, integrationId: string): string;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@uptick-ads/react-native-web-sdk",
+  "version": "0.2.0",
+  "description": "React Native component that runs the Uptick web SDK inside a WebView, inline or as a popup, with the web integration's parameters",
+  "keywords": [
+    "uptick",
+    "react-native",
+    "webview",
+    "offers",
+    "post-purchase"
+  ],
+  "homepage": "https://docs.uptick.com/publisher_sdks/react-native",
+  "bugs": {
+    "url": "https://github.com/uptick-ads/react-native-web-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uptick-ads/react-native-web-sdk.git"
+  },
+  "license": "UNLICENSED",
+  "author": "Uptick",
+  "main": "src/index.js",
+  "types": "index.d.ts",
+  "files": [
+    "src",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native": ">=0.73",
+    "react-native-webview": ">=13.10"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "check": "node --check src/index.js && node --check src/UptickFlow.js && node --check src/embedUrl.js && npm pack --dry-run",
+    "prepublishOnly": "npm run check"
+  },
+  "private": false
+}

package/src/UptickFlow.js

@@ -0,0 +1,166 @@
+import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Linking, Modal, Pressable, StyleSheet, View } from "react-native";
+import { WebView } from "react-native-webview";
+import { buildEmbedUrl, embedPath, pickFlowParams } from "./embedUrl";
+
+const DEFAULT_HOST = "api.uptick.com";
+const MAX_HEIGHT = 1400;
+
+// Messages from the host page that the component acts on itself; every message is also forwarded to `callback`.
+const SHOW_EVENTS = ["offer_viewed"];
+const HIDE_EVENTS = ["flow_complete", "flow_hidden"];
+
+const FILL = { position: "absolute", top: 0, left: 0, right: 0, bottom: 0 };
+
+// Renders an Uptick offer flow. Mount it where an inline offer should appear; when the placement is configured as a popup on the Uptick side it presents a modal over the whole screen instead, so switching a placement between inline and popup needs no app change.
+export function UptickFlow({
+  integrationId,
+  placement = "order_confirmation",
+  callback,
+  host = DEFAULT_HOST,
+  openUrl,
+  style,
+  modal = {},
+  webViewProps,
+  ...flowProps
+}) {
+  const [height, setHeight] = useState(0);
+  const [visible, setVisible] = useState(false);
+  // `null` until the page reports the rendered presentation; the placement's template decides it.
+  const [renderType, setRenderType] = useState(null);
+  const emit = useRef(callback);
+  emit.current = callback;
+
+  const params = pickFlowParams(flowProps);
+  const paramsKey = JSON.stringify(params);
+  const source = useMemo(
+    () => ({ uri: buildEmbedUrl({ host, integrationId, placement, params }) }),
+    // Callers pass fresh prop values each render; key on the serialised params so the page does not reload on every parent render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [host, integrationId, placement, paramsKey]
+  );
+  const ownPath = embedPath(host, integrationId);
+
+  const leave = useCallback(
+    (url) => {
+      // Linking.openURL must be called on Linking; a detached reference loses `this` and throws inside React Native.
+      const opener = openUrl || ((target) => Linking.openURL(target));
+      const report = (error) => emit.current && emit.current("open_url_failed", { url, message: String(error) });
+      try {
+        Promise.resolve(opener(url)).catch(report);
+      } catch (error) {
+        report(error);
+      }
+    },
+    [openUrl]
+  );
+
+  const onMessage = useCallback((event) => {
+    let message;
+    try {
+      message = JSON.parse(event.nativeEvent.data);
+    } catch (error) {
+      return;
+    }
+    const { name, data } = message;
+    if (name === "height") {
+      setHeight(Math.min(Math.max(Number(data && data.height) || 0, 0), MAX_HEIGHT));
+      return;
+    }
+    if (name === "render_type" && data && data.rendered) setRenderType(data.rendered);
+    if (SHOW_EVENTS.includes(name)) setVisible(true);
+    if (HIDE_EVENTS.includes(name)) setVisible(false);
+    if (emit.current) emit.current(name, data);
+  }, []);
+
+  // Any navigation away from the host page is a click-out: hand it to the system browser and keep the page where it is.
+  const onShouldStartLoadWithRequest = useCallback(
+    (request) => {
+      const url = request.url || "";
+      if (url.startsWith(ownPath) || url.startsWith("about:")) return true;
+      leave(url);
+      return false;
+    },
+    [ownPath, leave]
+  );
+
+  // The SDK opens accept links with window.open. Receiving them here keeps the page from navigating, so the SDK advances to the next offer while the user is in the browser.
+  // This matters on Android: turning off multiple windows instead makes the WebView start the navigation, the page sees pagehide, and the SDK freezes the current offer.
+  const onOpenWindow = useCallback((event) => leave(event.nativeEvent.targetUrl), [leave]);
+
+  const dismiss = useCallback(() => {
+    setVisible(false);
+    if (emit.current) emit.current("popup_dismissed", null);
+  }, []);
+
+  useEffect(() => {
+    setRenderType(null);
+    setHeight(0);
+    setVisible(false);
+  }, [source]);
+
+  const isPopup = renderType === "popup";
+  const contentHeight = Math.max(height, 1);
+  const {
+    scrimColor = "rgba(0, 0, 0, 0.45)",
+    cardStyle,
+    insets = { top: 24, bottom: 24 },
+    maxCardHeight = 620,
+  } = modal;
+
+  const webView = (
+    <WebView
+      source={source}
+      originWhitelist={["*"]}
+      javaScriptEnabled
+      domStorageEnabled
+      setSupportMultipleWindows
+      onMessage={onMessage}
+      onShouldStartLoadWithRequest={onShouldStartLoadWithRequest}
+      onOpenWindow={onOpenWindow}
+      onError={(event) => emit.current && emit.current("webview_error", { description: event.nativeEvent.description })}
+      onHttpError={(event) => emit.current && emit.current("webview_http_error", { status: event.nativeEvent.statusCode, url: event.nativeEvent.url })}
+      scrollEnabled={false}
+      nestedScrollEnabled
+      opaque={false}
+      {...webViewProps}
+      style={[styles.transparent, { height: isPopup ? Math.min(contentHeight, maxCardHeight) : contentHeight }, webViewProps && webViewProps.style]}
+    />
+  );
+
+  if (!isPopup) {
+    // Inline, and also the state before the page has reported anything: a collapsed slot in the host's layout.
+    // The WebView's own container is flex: 1, so the slot must carry an explicit height or it collapses to zero.
+    return <View style={[styles.transparent, { height: renderType === "inline" ? contentHeight : 1, overflow: "hidden" }, style]}>{webView}</View>;
+  }
+
+  // Popup: the page has already loaded inside the inline slot, so keep that WebView alive and move it into a system modal.
+  // React Native's Modal presents above the whole window regardless of where this component sits in the tree.
+  return (
+    <View style={[styles.transparent, { height: 0 }, style]}>
+      <Modal visible transparent animationType="fade" statusBarTranslucent onRequestClose={dismiss}>
+        <View style={FILL} pointerEvents={visible ? "auto" : "none"}>
+          <Pressable accessibilityRole="button" accessibilityLabel="Dismiss" style={[FILL, { backgroundColor: scrimColor, opacity: visible ? 1 : 0 }]} onPress={dismiss} />
+          <View pointerEvents="box-none" style={[FILL, styles.cardWrap, { paddingTop: insets.top, paddingBottom: insets.bottom, opacity: visible ? 1 : 0 }]}>
+            <View style={[styles.card, { height: Math.min(contentHeight, maxCardHeight) }, cardStyle]}>{webView}</View>
+          </View>
+        </View>
+      </Modal>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  transparent: { backgroundColor: "transparent" },
+  cardWrap: { justifyContent: "center", paddingHorizontal: 16 },
+  card: {
+    backgroundColor: "#fff",
+    borderRadius: 16,
+    overflow: "hidden",
+    shadowColor: "#000",
+    shadowOpacity: 0.25,
+    shadowRadius: 20,
+    shadowOffset: { width: 0, height: 10 },
+    elevation: 12,
+  },
+});

package/src/embedUrl.js

@@ -0,0 +1,50 @@
+// Builds the URL of the host page served by the Uptick API for WebView embeds.
+// Flow parameters travel in the URL fragment, which browsers never send to the server, so customer and order details stay out of request logs and CDN caches.
+
+// The web SDK's parameter list (see docs.uptick.com/publishers/web); anything else passed to the component is ignored rather than forwarded.
+export const FLOW_PARAMS = [
+  // Site
+  "site_id",
+  // User
+  "customer_id",
+  "first_name",
+  "locale",
+  // Order
+  "order_id",
+  "order_name",
+  "payment_method",
+  "currency",
+  "total_price",
+  "shipping_price",
+  "discount",
+  "zip",
+  "province",
+  "country_code",
+];
+
+function encodeQuery(params) {
+  return Object.keys(params)
+    .filter((key) => params[key] !== undefined && params[key] !== null && params[key] !== "")
+    .map((key) => `${encodeURIComponent(key)}=${encodeURIComponent(String(params[key]))}`)
+    .join("&");
+}
+
+export function pickFlowParams(props) {
+  const out = {};
+  FLOW_PARAMS.forEach((key) => {
+    if (props[key] !== undefined && props[key] !== null) out[key] = props[key];
+  });
+  return out;
+}
+
+export function embedPath(host, integrationId) {
+  return `https://${host}/v1/places/${encodeURIComponent(integrationId)}/embed`;
+}
+
+export function buildEmbedUrl({ host, integrationId, placement, params }) {
+  if (!integrationId) throw new Error("UptickFlow: integrationId is required");
+  // The page renders whatever presentation the placement's template defines; `native` only asks it to leave the popup chrome to the app.
+  const search = encodeQuery({ placement, variant: "native" });
+  const fragment = encodeQuery(params || {});
+  return `${embedPath(host, integrationId)}?${search}${fragment ? `#${fragment}` : ""}`;
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { UptickFlow } from "./UptickFlow";
+export { buildEmbedUrl, embedPath, pickFlowParams, FLOW_PARAMS } from "./embedUrl";