|
| 1 | +--- |
| 2 | +name: appgram-react-native-sdk |
| 3 | +description: "Integrate or maintain the Appgram React Native SDK (@appgram/react-native): install peers, configure AppgramProvider, use built-in components/hooks for feedback, roadmap, releases, help center, support, surveys, blog, status, chat, apply theming, and run build/lint/docs tasks." |
| 4 | +--- |
| 5 | + |
| 6 | +# Appgram React Native SDK |
| 7 | + |
| 8 | +## When to use |
| 9 | +- You need to embed Appgram feedback/roadmap/changelog/help/support/surveys/blog/status/chat in a React Native app. |
| 10 | +- You are wiring Appgram headless hooks into custom UI. |
| 11 | +- You are maintaining this SDK: build, lint, docs, publish, or debugging peer/native issues. |
| 12 | + |
| 13 | +## Prerequisites |
| 14 | +- React Native ≥0.70, React 18, Metro; iOS requires CocoaPods, Android uses autolinking. |
| 15 | +- Peer deps: `@react-native-async-storage/async-storage`, `lucide-react-native`, `react-native-svg`, `react-native-markdown-display`, `react-native-render-html`. |
| 16 | +- Install peers after the SDK, then `npx pod-install` for iOS. |
| 17 | + |
| 18 | +## Quick start |
| 19 | +- Install: `npm install @appgram/react-native` then peer deps `npm install @react-native-async-storage/async-storage lucide-react-native react-native-svg react-native-markdown-display react-native-render-html`. |
| 20 | +- iOS: run `npx pod-install` after installing peers. |
| 21 | +- Wrap your app once: |
| 22 | +```tsx |
| 23 | +<AppgramProvider config={{ projectId: 'YOUR_PROJECT_ID', orgSlug: 'org', projectSlug: 'project', apiUrl: 'https://api.appgram.dev', theme: { mode: 'system' } }}> |
| 24 | + {children} |
| 25 | +</AppgramProvider> |
| 26 | +``` |
| 27 | +- Use ready UI or headless hooks: |
| 28 | +```tsx |
| 29 | +<WishList onWishPress={(wish) => console.log(wish)} /> |
| 30 | +<SupportForm onSuccess={() => Alert.alert('Sent')} /> |
| 31 | +// Hooks |
| 32 | +const { wishes, isLoading, refetch } = useWishes() |
| 33 | +const { vote } = useVote() |
| 34 | +``` |
| 35 | + |
| 36 | +## Feature map (components → hooks) |
| 37 | +- Feedback: `WishList`, `WishCard`, `VoteButton`, `WishDetailModal`, `SubmitWishSheet` → `useWishes`, `useVote`, `useComments`. |
| 38 | +- Roadmap: `RoadmapBoard` → `useRoadmap`. |
| 39 | +- Releases/Changelog: `Releases`, `ReleaseList`, `ReleaseDetail` → `useReleases`, `useRelease`. |
| 40 | +- Help Center: `HelpCenter`, `HelpFlowCard`, `HelpFlowDetail`, `HelpArticleCard`, `HelpArticleDetail` → `useHelpCenter`, `useHelpFlow`, `useHelpArticle`. |
| 41 | +- Support & Forms: `SupportForm`, `FormRenderer` → `useSupport`, `useForm`, `useFormSubmit`. |
| 42 | +- Surveys: `SurveyForm` → `useSurvey`, `useSurveySubmit`. |
| 43 | +- Blog: `Blog`, `BlogList`, `BlogCard`, `BlogPostDetail` → `useBlogPosts`, `useBlogPost`, `useBlogCategories`, `useFeaturedPosts`. |
| 44 | +- Status: `StatusBoard` → `useStatus`. |
| 45 | +- Chat: `ChatScreen` (`ChatSource` type available) – pull data via context client as needed. |
| 46 | +- Base UI bits: `Button`, `Card`, `Badge`, `Input` for consistent styling. |
| 47 | + |
| 48 | +**Hook pattern:** hooks return data + `isLoading` (and often `error`, `refetch`); many accept `refreshInterval` and filter props (see exported option/result types). |
| 49 | + |
| 50 | +### Props & options details |
| 51 | +- Hooks: see `references/hooks.md` (options, return shapes, behaviors like refreshInterval and fingerprinting). |
| 52 | +- Components: see `references/components.md` (purpose + key props per component). |
| 53 | + |
| 54 | +## Configuration & theming |
| 55 | +- `AppgramProvider.config`: |
| 56 | + - `projectId` (required), `orgSlug`/`projectSlug` for routing. |
| 57 | + - `apiUrl` override for self-host/staging (default `https://api.appgram.dev`). |
| 58 | + - `enableFingerprinting` (default true) uses AsyncStorage + device info for anonymous votes. |
| 59 | + - `theme`: `mode` (`light`|`dark`|`system`), optional `lightColors`/`darkColors` partial overrides; defaults from Hazel design system. |
| 60 | +- Access context: `useAppgramContext()` → `{ client, config, fingerprint, theme }`. |
| 61 | +- Theming in custom UI: `useAppgramTheme()` → `{ colors, spacing, radius, typography, isDark, mode }`; palette exports `lightColors`, `darkColors`, scales `spacing`, `radius`, `typography` for reuse. |
| 62 | + |
| 63 | +### Sample themed usage |
| 64 | +```tsx |
| 65 | +const { colors, spacing, radius } = useAppgramTheme() |
| 66 | +return ( |
| 67 | + <Card style={{ backgroundColor: colors.background, padding: spacing.lg, borderRadius: radius.lg }}> |
| 68 | + <WishList submitButtonText=\"Suggest a feature\" /> |
| 69 | + </Card> |
| 70 | +) |
| 71 | +``` |
| 72 | + |
| 73 | +## API client |
| 74 | +- Get the instantiated `AppgramClient` from context: `const { client } = useAppgramContext()`. |
| 75 | +- Methods mirror hooks (e.g., `client.getWishes`, `client.vote`, `client.getRoadmap`); responses follow `ApiResponse` / `PaginatedResponse` types exported from `types`. |
| 76 | +- Use when you need imperative flows (e.g., prefetch before navigation) or custom caching. |
| 77 | + |
| 78 | +## Local development & maintenance (this repo) |
| 79 | +- Install dev deps: `npm install`. |
| 80 | +- Lint: `npm run lint`; typecheck: `npm run typecheck`. |
| 81 | +- Build package: `npm run build` (builder-bob, outputs to `lib/`); runs automatically on `npm install` via `prepare`. |
| 82 | +- Docs: `npm run docs:json` (typedoc) → `docs.json`; `npm run docs:transform` (uses `transform-docs.js`); `npm run docs:build` to do both. |
| 83 | +- Publish (when ready): `npm run release` (assumes npm auth + version bump). Keep `react-native-builder-bob` config in `package.json`; build uses `tsconfig.build.json`. |
| 84 | + |
| 85 | +## Platform setup & debugging |
| 86 | +- Install order, pod install, Gradle check, cache clears, and platform notes: `references/platform-setup.md`. |
| 87 | + |
| 88 | +## Common recipes |
| 89 | +- **Custom vote button:** use `useVote`; pass `onVote` to sync local counts; guard for missing fingerprint by showing a prompt to enable cookies/storage. |
| 90 | +- **Support with magic link:** use `useSupport`; call `requestMagicLink(email)` then `verifyToken(token)`; tickets also saved locally (`storedTickets`, `clearStoredTickets`). |
| 91 | +- **Embed changelog tab:** stack navigator screen with `Releases`; on press, navigate to detail screen wrapping `ReleaseDetail`. |
| 92 | +- **Anonymous wishlist:** keep `enableFingerprinting` on (default); if privacy requires, set false and disable voting UI. |
| 93 | +- **Blog index + detail:** `BlogList` for landing; use `useBlogPosts` if you need infinite scroll; route to `BlogPostDetail` on press. |
| 94 | +- **Status page banner:** call `useStatus({ slug, refreshInterval: 60000 })` and render a small inline banner with `data.status`. |
| 95 | +- See ready-to-paste code in `references/snippets.md`. |
| 96 | + |
| 97 | +## Troubleshooting |
| 98 | +- Missing peer deps / native linking: ensure all peers installed; run `npx pod-install` for iOS; clear Metro cache if symbols missing. |
| 99 | +- Theming not applying: verify `theme.mode` not overridden by system; pass both light/dark overrides when customizing primary/background/foreground. |
| 100 | +- Anonymous voting blocked: set `enableFingerprinting=false` if fingerprint cannot be generated, or ensure AsyncStorage works in environment. |
| 101 | +- API errors: confirm `projectId`/slugs and `apiUrl`; use `client` methods to inspect `response.success` and `response.error`. |
| 102 | +- Version support: built for React Native ≥0.70 and React 18+. Ensure `react-native-svg` and `lucide-react-native` versions stay compatible. |
| 103 | + |
| 104 | +## References (load on demand) |
| 105 | +- Hooks options/returns: `references/hooks.md` |
| 106 | +- Components props notes: `references/components.md` |
| 107 | +- API client methods + notes: `references/api-client.md` |
| 108 | +- Platform setup & debugging: `references/platform-setup.md` |
| 109 | +- Practical code snippets: `references/snippets.md` |
0 commit comments