# QwikCard SDK Handover Guide (v2.3.2)

> [!NOTE]
> This SDK is a **React Native Library**, not a standalone application. In v2.3.2, the primary UI is delivered via a **WebView-embedded Widget UI** (the Playbasis Widget SDK), while API calls remain on the React Native side.

This document provides instructions for the Qwik team to integrate the latest Playbasis gamification experience into the QwikCard mobile SDK.

## Overview of Changes

The v2.3.2 update shifts the SDK to a **WebView + bridge** architecture, focused on:

- **One-Line Integration**: Use `<QwikCardApp />` to render the full experience.
- **Widget UI Parity**: UI comes from the Playbasis Widget SDK (web UI) embedded into the RN SDK.
- **Direct-to-Tenant Support**: Calls go through APIM using `Ocp-Apim-Subscription-Key` + `X-Tenant-ID` headers (configured via props).
- **Key Handling**: The APIM subscription key stays in React Native; the WebView requests data via a message bridge.
- **Bundle Workflow**: See [QWIK_SDK_BUNDLE_WORKFLOW.md](../../QWIK_SDK_BUNDLE_WORKFLOW.md) for the slim bundle + PLAY tab shipping checklist.

## 📦 Changeset Summary

### Key Implementation Notes

- `QwikCardApp` now renders a `react-native-webview` with embedded Widget SDK assets.
- The WebView requests bootstrap data (player, balances, quests, badges) from React Native via a REQUEST/RESPONSE message bridge.

## 📦 Installation (Private Distribution)

To maintain privacy while ensuring "ease of use," we recommend one of the following methods for integrating the SDK into your project:

### 1. Local Package Installation (Recommended for Testing)

You can install the provided tarball directly into your mSDK project:

```bash
npm install ./path/to/qwikcard-sdk-v2.3.2.tar.gz
```

This adds the SDK to your `node_modules` and `package.json` just like a public package.

### 2. Private Git Dependency

If you host this in a private repository, you can install it directly via SSH:

```bash
npm install git+ssh://git@github.com:your-org/qwikcard-sdk.git#v2.3.2
```

### 3. Private Registry (npmjs)

For consistent distribution, the SDK is published to the private npmjs scope under `@playbasis-ai`:

1. **Install via NPM**:
   ```bash
   npm install @playbasis-ai/qwikcard-sdk
   ```
2. **Authenticate**: ensure your npmjs token has access to the `@playbasis-ai` org.

## 🛠️ One-Line Integration (Component as a "Method")

If your team prefers an "invocation" style, simply wrap the `QwikCardApp` in a single screen or a conditional overlay. This effectively "invokes" the entire template library in one line:

```tsx
import { QwikCardApp } from '@playbasis-ai/qwikcard-sdk';

const MyScreen = () => (
  <QwikCardApp
    apiKey="YOUR_API_KEY"
    tenantId="YOUR_TENANT_ID"
    playerId="USER_123"
    baseUrl="https://api.playbasis.com" // optional
    leaderboardId="YOUR_LEADERBOARD_ID" // optional
  />
);
```

## 🛠️ Integration Notes

- Ensure your host app installs `react-native-webview` (peer dependency).
- If your host app uses strict network allowlists / ATS settings, ensure the APIM base URL is permitted.

## 🌐 Targeting Web (Vite/Next.js)

The SDK exports React Native components/hooks as well. If you use those exports in a web project (like Vite or Next.js), you must use **`react-native-web`** to alias the components:

1.  **Install Aliases**: `npm install react-native-web`
2.  **Configure Vite**:
    ```javascript
    // vite.config.ts
    resolve: {
      alias: {
        'react-native': 'react-native-web',
      }
    }
    ```

## 🧪 Verification Plan

Before deployment, verify the following:

1.  **WebView Renders**: The Widget UI loads and is interactive.
2.  **Bootstrap Bridge**: Player/balances/quests/badges show up (no infinite loading).
3.  **Key Safety**: `apiKey` is only provided to the React Native layer (not persisted inside the WebView).

Current limitations (v2.2.7):

- Leaderboard data requires passing a concrete `leaderboardId`. If omitted, the widget will show an empty leaderboard section.
- Activity chart data is returned as an empty array unless/until an activity endpoint is provided.

## 🚨 Troubleshooting

### "Failed to resolve entry for package"

Ensure you are using v2.3.2 which includes the compiled `dist/` folder. If you are building from source, ensure your bundler is configured to transpile `.ts` files inside `node_modules`.

### "Failed to resolve import 'react-dom/client'"

This typically happens if your web project is missing the `react-dom` dependency. Ensure it is installed:

```bash
npm install react react-dom
```

### "Can't find variable: Text/View"

This means `react-native-web` is not correctly aliased in your bundler. Ensure the alias is set up so that the web project knows how to render native components.

---

_For technical support during integration, contact the Playbasis Engineering Team._