@playbasis-ai/qwikcard-sdk

Official React Native SDK for Playbasis gamification integration

Features

• 🎮 Full Gamification Suite - Points, quests, badges, rewards, leaderboards
• ⚡ Real-time Updates - React hooks with automatic state management
• 🔒 Secure by Design - No credentials stored, idempotent requests
• 🧩 Widget UI via WebView - Full Playbasis Widget experience embedded in RN
• 🔄 Offline-Friendly - Graceful error handling

Installation

npm install @playbasis-ai/qwikcard-sdk

Peer Dependencies

You must install the following dependencies in your project:

npm install react-native-linear-gradient react-native-svg react-native-webview

Local Installation (if not published to npm)

If this package is not published to npm, you can install it locally in your project using one of the following methods:

1. From a Local Folder (Symlink for Development)

Unzip or place the SDK folder (with package.json) somewhere on your machine, e.g., ~/playbasis-sdk/. In your project, run:

yarn add /absolute/path/to/playbasis-sdk
# or
npm install /absolute/path/to/playbasis-sdk

2. From a Tarball (.tgz or .zip)

If you have a file like playbasis-qwikcard-sdk-1.0.0.zip or .tgz, you can install directly:

yarn add ./client-sdks/qwikcard-sdk/playbasis-qwikcard-sdk-1.0.0.zip
# or
npm install ./client-sdks/qwikcard-sdk/playbasis-qwikcard-sdk-1.0.0.zip

3. npm/yarn link (for active development)

In the SDK folder:

npm link
# or
yarn link

In your project folder:

npm link @playbasis-ai/qwikcard-sdk
# or
yarn link @playbasis-ai/qwikcard-sdk

4. From a Git Repository

If the SDK is hosted in a private Git repo:

yarn add git+https://github.com/your-org/playbasis-qwikcard-sdk.git
# or
npm install git+https://github.com/your-org/playbasis-qwikcard-sdk.git

If the package is published to npm, you can install as usual:

npm install @playbasis-ai/qwikcard-sdk
# or
yarn add @playbasis-ai/qwikcard-sdk

Requirements

• React Native >= 0.70.0
• React >= 18.0.0

Quick Start

1. One-Line Integration (Recommended)

QwikCardApp renders the full Playbasis experience using a WebView-embedded Widget UI, while keeping API calls on the React Native side.

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

export default function RewardsAndGamificationScreen() {
  return (
    <QwikCardApp
      apiKey="YOUR_SUBSCRIPTION_KEY"
      tenantId="YOUR_TENANT_ID"
      playerId={currentUser.playbasisPlayerId}
      baseUrl="https://api.playbasis.com" // optional
      leaderboardId="YOUR_LEADERBOARD_ID" // optional
    />
  );
}

Notes:

• leaderboardId is optional because the Playbasis API requires a concrete leaderboard identifier. If omitted, the widget will render with an empty leaderboard section.
• Activity charts are returned as an empty array in v1.3.0 unless/until an activity endpoint is added to the API.

2. Provider + Hooks (Optional / Advanced)

If you need direct access to the API client for custom UI/logic, you can still use the provider + hooks.

Wrap Your App

import { PlaybasisProvider } from '@playbasis-ai/qwikcard-sdk';

export default function App() {
  return (
    <PlaybasisProvider
      apiKey="YOUR_SUBSCRIPTION_KEY"
      tenantId="qwikcard"
      playerId={currentUser.playbasisPlayerId}
    >
      <YourApp />
    </PlaybasisProvider>
  );
}

2. Use Hooks (with your own screens)

import { useQuests, useRewards, useBadges, usePoints } from '@playbasis-ai/qwikcard-sdk';

function RewardsScreen() {
  const { rewards } = useRewards();
  const { badges } = useBadges();
  const { xp, qwikCoins } = usePoints();

  return (
    <View>
      <Text>XP: {xp}</Text>
      <Text>Qwik Coins: {qwikCoins}</Text>
      {/* Render rewards + badges here */}
    </View>
  );
}

3. Use Components (with your own screens)

import { QuestProgress, RewardCard, BadgeIcon, PointsBalance } from '@playbasis-ai/qwikcard-sdk';

function QuestsScreen() {
  const { quests } = useQuests();
  const { balances } = usePoints();

  return (
    <ScrollView>
      <PointsBalance balances={balances} />
      {quests.map((quest) => (
        <QuestProgress key={quest.id} quest={quest} />
      ))}
    </ScrollView>
  );
}

API Client (Direct Access)

For custom operations:

import { usePlaybasis } from '@playbasis-ai/qwikcard-sdk';

function TransactionLogger() {
  const { client, playerId } = usePlaybasis();

  const logPurchase = async (transaction) => {
    await client.trackEvent({
      type: 'card.purchase',
      playerId,
      referenceId: transaction.i2c_trans_id,
      data: {
        amount: transaction.amount,
        mcc: transaction.mcc,
        category: transaction.category,
      },
    });
  };

  return { logPurchase };
}

Event Types

// XP values follow the QwikCard XP rulebook in QWIK_PLAYBASIS_GAMIFICATION_DESIGN.md.
type QwikCardEventType =
  | 'auth.signup' // Account created (+50 XP, once)
  | 'auth.login' // Daily login (+5 XP, 1/day)
  | 'profile.updated' // Profile progress (+25 XP, max 3 lifetime)
  | 'card.activated' // Card activation (+150 XP, once)
  | 'card.deposit' // Funding action (+40 XP, 1/day)
  | 'budget.created' // Budget created (+120 XP, 1/quarter)
  | 'transactions.viewed' // Transaction review (+10 XP, 1/day)
  | 'credit.score_viewed' // Credit score check (+40 XP, 1/week)
  | 'qwikit.sent' // P2P transfer sent (+20 XP, max 5/day)
  | 'qwikit.received' // P2P transfer received (+10 XP, max 5/day)
  | 'qwikit.requested' // P2P transfer requested (+10 XP, max 5/day)
  | 'referral.completed' // Referral success (+250 XP, max 10 lifetime)
  | 'learning.lesson_started' // Lesson started (+10 XP, max 3/day)
  | 'learning.lesson_completed' // Lesson completed (+75 XP, max 3/day)
  | 'offers.map_viewed'; // Offers map viewed (+5 XP, 1/day)

API Reference

Hooks

| Hook | Description | | ---------------- | ---------------------------------- | | usePoints() | Player point balances, earn points | | useQuests() | Active and completed quests | | useBadges() | Earned and available badges | | useRewards() | Reward catalog and redemption | | usePlaybasis() | Direct client access |

Components

| Component | Description | | --------------------- | ------------------------------- | | <PlaybasisProvider> | Context provider (required) | | <PointsBalance> | Display point balances | | <QuestProgress> | Quest progress card | | <RewardCard> | Reward item with redeem button | | <BadgeIcon> | Badge display with earned state |

Security

• ✅ No credentials stored in SDK
• ✅ All requests use HTTPS
• ✅ Idempotency keys prevent duplicate operations
• ✅ Safe JSON parsing (handles malformed responses)

Support

Contact Playbasis support for:

• API credentials
• Integration assistance
• Custom implementations

© 2025 Playbasis. All rights reserved.