> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openv2.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrations

> Connect third-party APIs and services to your Openv2 Expo project.

Third-party APIs let your app send messages, take payments, show maps, and call AI models — without building that infrastructure yourself. Openv2's AI assistant can wire up almost any HTTP API once you give it the right context.

## The general pattern

<Steps>
  <Step title="Pick your API">
    Decide whether you need a REST or GraphQL API. Check whether the provider offers an official SDK with React Native or Expo support — a first-party SDK is usually easier to integrate and maintain than raw HTTP calls.
  </Step>

  <Step title="Handle secrets safely">
    If the API requires a private key, keep it on a server you control and proxy requests through it. Only use `EXPO_PUBLIC_*` environment variables for non-secret values like base URLs or public API keys that the provider explicitly allows in client code.

    <Warning>
      Do not embed private API keys in your app bundle. Anyone who downloads the app can extract strings from the binary. Route sensitive calls through your own backend instead.
    </Warning>
  </Step>

  <Step title="Prompt Openv2 to wire it up">
    Give the AI the base URL, the auth pattern, and a description of how you want to use the API in your UI. A prompt like this works well:

    > "Add a `lib/api/weather.ts` client for `https://api.openweathermap.org/data/2.5`, typed responses, and error handling; call it from Home with loading and error UI."

    The AI will create the typed client, handle errors, and update your screen component with loading and error states.
  </Step>
</Steps>

## Common integration categories

<CardGroup cols={2}>
  <Card title="Auth" icon="lock" href="/backend">
    Use Supabase Auth for email/password and OAuth providers. See the Backend page for setup guidance.
  </Card>

  <Card title="Payments" icon="credit-card" href="/builds-mobile">
    RevenueCat (in-app subscriptions) and Stripe (web payments) are common choices. Both require native configuration and store-side setup for production.
  </Card>

  <Card title="Maps and location" icon="map-pin" href="/expo-and-openv2">
    Use provider SDKs that are compatible with Expo. Check Expo's docs for recommended map libraries and any permissions your app needs to declare.
  </Card>

  <Card title="AI features" icon="wand-magic-sparkles" href="/backend">
    Call model APIs from your own backend rather than directly from the app. This keeps your API keys secure and lets you control rate limiting and costs.
  </Card>
</CardGroup>

## Reliability best practices

Integrations fail. Networks drop, rate limits hit, and third-party services go down. Build your UI to handle these cases from the start.

**Timeouts.** Set explicit timeout values on every request. A hung fetch with no timeout will leave your UI frozen indefinitely.

**Rate limits (429).** If you call an API from multiple users, you will eventually hit a 429. Catch these responses and show a clear message rather than a generic error.

**Offline states.** On mobile, users regularly lose connectivity. Show a meaningful UI when requests fail due to no network — don't just show a blank screen or crash.

**Retry carefully.** Only add automatic retry for safe, idempotent reads. Never auto-retry a write (a form submission, a payment, a message send) — you may create duplicate records.

## Testing: browser vs device

<Tabs>
  <Tab title="Browser preview">
    The browser preview is the fastest way to develop and iterate on your integration's UI. Use it to build loading states, error states, and happy-path flows.

    Network requests work in the browser preview, so you can call real APIs during development. Just confirm that CORS is not blocked for browser origins if you're hitting an API directly.
  </Tab>

  <Tab title="Real device">
    Some integrations only work correctly on a physical device:

    * **Camera and microphone access** for apps that capture media before uploading
    * **Push notifications** end-to-end (token registration, delivery, tap handling)
    * **Deep links** from external apps or email confirmation flows
    * **Native SDK behavior** for packages that have different implementations on device vs web

    Use [Expo Go or a development build](/test-on-device) to verify these on hardware before submitting to the stores.
  </Tab>
</Tabs>

***

<CardGroup cols={2}>
  <Card title="How to prompt successfully" icon="message" href="/prompting">
    Patterns for writing prompts that produce clean code and fewer follow-up turns.
  </Card>

  <Card title="Backend and data" icon="database" href="/backend">
    Set up auth and a database with OpenV2 Cloud or your own Supabase project.
  </Card>
</CardGroup>