Skip to content

Sync engage-native docs with v1.18.4 #297

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Sync engage-native docs with v1.18.4 #297

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 43 additions & 16 deletions repositories/d-sports-engage-native.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,22 +6,25 @@ icon: "smartphone"

## Overview

**d-sports-engage-native** (package name: `engage-native`) is the native mobile app for D-Sports. It mirrors the core PWA experience on iOS and Android: wallet, shop, leaderboard, locker room, and profile.
**d-sports-engage-native** (package name: `engage-native`, v1.18.4) is the native mobile app for D-Sports. It mirrors the core PWA experience on iOS and Android: wallet, shop, leaderboard, locker room, and profile.

- **Run:** `bunx expo start` or `bun run start` — then press `a` for Android or `i` for iOS, or scan the QR code with Expo Go.

## Tech stack

| Category | Technology |
| ---------- | ------------------------- |
| Framework | Expo 54, React Native 0.81, React 19 |
| Framework | Expo 55, React Native 0.83, React 19 |
| Auth | Clerk (Expo) |
| Payments | RevenueCat (react-native-purchases) |
| Web3 | Thirdweb |
| State | Zustand |
| State | Zustand 5 |
| Storage | MMKV |
| UI | Lucide React Native |
| Navigation | Expo Router |
| Navigation | Expo Router (file-based, typed routes) |
| Monitoring | Sentry |
| Push | OneSignal |
| Widgets | expo-widgets (iOS), react-native-android-widget |
| Package | Bun |

## Features
Expand All @@ -30,27 +33,22 @@ icon: "smartphone"
- **Shop** — Collectibles, cart, coin bundles, checkout
- **Leaderboard** — Rankings and filters
- **Locker room** — Social feed and engagement
- **Profile** — User profile and settings
- **Profile** — User profile, achievements, milestone avatars, and settings
- **Theme** — Dark/light mode (default dark)

## What changed since last docs sync

- Team-aware experiences were expanded to align with backend team/favorites behavior.
- Quest and rewards surfaces were updated to support per-team progression and pass-aware eligibility.
- Pack opening and odds disclosure UX were upgraded with safer interactions and clearer status/error handling.
- Settings and account flows were expanded, including in-app account deletion and richer support/data controls.
- **Widgets** — iOS and Android home screen widgets showing rank or wallet points
- **OTA updates** — EAS Update for over-the-air deploys on push to `develop` or `main`

## Backend integration surfaces

- Primary API source: `d-sports-api` under `/api/*`.
- Native app consumes team, league, quest, reward, wallet, commerce, and social endpoints.
- Retry/caching logic and auth token injection are centralized in app API client modules.
- Retry/caching logic and auth token injection are centralized in `lib/api/client.ts`.

## Quest and pass UX integration

- Quest UI now reflects team-scoped eligibility and pass-gated progression where applicable.
- Quest UI reflects team-scoped eligibility and pass-gated progression where applicable.
- Reward presentation differentiates free/unpaid states and claimability.
- Native progression state is expected to mirror backend eligibility and completion semantics.
- Native progression state mirrors backend eligibility and completion semantics.

## Team-aware experiences

Expand All @@ -62,15 +60,44 @@ icon: "smartphone"
- Native odds disclosure behavior is documented with policy-aligned copy and evidence requirements.
- Disclosure values must come from backend payloads and remain visible/accessible near open actions.

## Environment variables

Only `EXPO_PUBLIC_*` keys are accessible at runtime. You need to configure the following in a `.env` file:

| Variable | Purpose |
| -------- | ------- |
| `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY` | Clerk authentication |
| `EXPO_PUBLIC_API_URL` | Backend API base URL |
| `EXPO_PUBLIC_TW_CLIENT_ID` | Thirdweb client ID (Web3) |
| `EXPO_PUBLIC_REVENUECAT_API_KEY` | RevenueCat API key |
| `EXPO_PUBLIC_REVENUECAT_APPSTORE_ID` | RevenueCat App Store ID |
| `EXPO_PUBLIC_REVENUECAT_ENTITLEMENT` | RevenueCat entitlement identifier |
| `EXPO_PUBLIC_SUPABASE_URL` | Supabase project URL |
| `EXPO_PUBLIC_SUPABASE_KEY` | Supabase publishable key |

## Getting started

1. Clone the repository and run `bun install`.
2. Configure environment (Clerk, RevenueCat, Thirdweb, API base URL) per repo README.
2. Copy `.env.example` to `.env` and fill in the required keys above.
3. Run `bunx expo start`.
4. For development builds: `bun run build:dev` (EAS) or run with Expo dev client.

The app targets both native and web (responsive) and uses the same backend (d-sports-api) as the PWA for API and checkout flows.

## EAS build profiles

The project uses [EAS Build](https://docs.expo.dev/build/introduction/) with the following profiles defined in `eas.json`:

| Profile | Use case |
| ------- | -------- |
| `development` | Dev client build with simulator support |
| `development-device` | Dev client build for physical devices |
| `preview` | Internal distribution (APK on Android) |
| `staging` | Auto-increment staging builds |
| `production` | Auto-increment production builds with App Store / Play Store submission |

A GitHub Actions workflow (`.github/workflows/eas-update.yml`) publishes OTA updates via `eas update` on pushes to `develop` and `main`.

## Deep dives

- [Architecture](/repositories/d-sports-engage-native/architecture)
Expand Down
15 changes: 14 additions & 1 deletion repositories/d-sports-engage-native/architecture.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,19 @@ The native app is structured around Expo Router screens, feature-oriented compon

## Platform-specific behavior

- iOS/Android platform differences are handled in native-specific components and runtime checks.
- iOS/Android platform differences are handled in native-specific layout files and runtime checks.
- Web-target support exists but mobile behavior is primary for interaction and performance design.
- Haptics, modal controls, and animation handling are implemented with platform-safe fallbacks.

### Tab bar

The tab bar uses a platform-split approach:

- **iOS** (`_layout.ios.tsx`) — uses `NativeTabs` from `expo-router/unstable-native-tabs` with the system tab bar. The wallet tab shows a numeric badge for unopened packs. The bar uses `systemChromeMaterialDark` with gold selection (`#FFD700`).
- **Android and web** (`_layout.tsx`) — uses JS `Tabs` with a hidden default bar and a custom `PillTabBar` overlay. Android applies `expo-blur` for a blur effect.
- **Shared config** (`tab-config.ts`) — defines tab order, SF Symbol pairs for iOS, and helper functions like `getActiveTabIndex` so `/profile/[handle]` does not highlight the Profile tab.

### Widgets

- **iOS** — `expo-widgets` provides a `RankOrPointsWidget` (small/medium) and a `LiveStatusActivity` Live Activity.
- **Android** — `react-native-android-widget` provides a `RankOrPointsWidget` (3×2 cells, 30-minute refresh).