### Run pod install for iOS

Source: https://paywallo.com.br/docs/install

Enter the ios folder and run pod install. Autolinking handles the rest. No action needed for Android.

```bash
cd ios && pod install
```

--------------------------------

### Install Paywallo SDK with npm

Source: https://paywallo.com.br/docs/install

Run in the project root to install the Paywallo SDK package. Works with yarn add or pnpm add as well.

```bash
npm install @virex-tech/paywallo-sdk
```

--------------------------------

### Verify SDK initialization log

Source: https://paywallo.com.br/docs/install

With debug: __DEV__ enabled, this log appears in the console when the app runs, confirming the SDK started.

```text
[Paywallo] initialized successfully
```

--------------------------------

### Wait for SDK readiness before identify/track

Source: https://paywallo.com.br/docs/install

Use waitUntilReady() before identify/track on cold start. Without it, the SDK may not be ready and will throw "SDK not initialized". The properties.userId is required to link the device to the user.

```tsx
// No boot (useEffect ou equivalente):
await PaywalloClient.waitUntilReady();
await PaywalloClient.identify({
  email: user.email,
  properties: { userId: user.id }, // obrigatório pra linkar o device ao usuário
});
```

--------------------------------

### Rebuild development build after SDK install

Source: https://paywallo.com.br/docs/install

If you already have a development build installed, rebuild it after installing the SDK. New native modules do not appear with just a JS reload.

```bash
npx expo run:ios
# ou
npx expo run:android
```

--------------------------------

### Install required Expo peer dependencies

Source: https://paywallo.com.br/docs/install

expo-application, expo-device, and expo-localization are mandatory peer dependencies. The SDK imports them statically; without them the build breaks with no fallback.

```bash
npx expo install expo-application expo-device expo-localization
```

--------------------------------

### Request ATT permission before mounting Provider (iOS)

Source: https://paywallo.com.br/docs/install

On iOS, request App Tracking Transparency permission and wait for the user's response before rendering PaywalloProvider. If the Provider mounts first, the SDK initializes with attStatus=undetermined, no IDFA, and no madid in CAPI, degrading install attribution. Requires NSUserTrackingUsageDescription in Info.plist.

```tsx
import * as TrackingTransparency from "expo-tracking-transparency";
import { Platform } from "react-native";

async function bootstrap() {
  if (Platform.OS === "ios") {
    await TrackingTransparency.requestTrackingPermissionsAsync();
  }
  // só agora renderiza <PaywalloProvider>
}
```

--------------------------------

### Chamar complete() para finalizar o onboarding

Source: https://paywallo.com.br/docs/onboarding-dropout

Use este snippet quando o usuário chega ao fim do onboarding (última tela, paywall, home). Sem complete(), a taxa de conclusão fica em 0%. Em teste A/B, passe o mesmo variantKey usado nos steps.

```typescript
import { onboardingManager } from "@virex-tech/paywallo-sdk";

// quando o usuário termina o fluxo (chegou na última tela ou no paywall)
await onboardingManager.complete();

// Em teste A/B, passe o mesmo variantKey usado nos steps
await onboardingManager.complete({ variantKey: "variant_b" });
```

--------------------------------

### Mark onboarding steps with onboardingManager.step()

Source: https://paywallo.com.br/docs/onboarding-dropout

Use this snippet to mark each onboarding screen with a unique name and its order in the funnel. The order argument is required; without it the backend cannot build the funnel sequence. Call it on screen mount, e.g., inside a useEffect, and call it again for the same step if the user returns; the backend keeps the most advanced progress.

```typescript
import { onboardingManager } from "@virex-tech/paywallo-sdk";

// chama em cada tela do seu onboarding, passando o order da tela
await onboardingManager.step("welcome", 0);
await onboardingManager.step("age_selection", 1);
await onboardingManager.step("goal", 2);
```

--------------------------------

### Track onboarding steps across three screens with onboardingManager

Source: https://paywallo.com.br/docs/onboarding-dropout

Use this snippet to track user progress through a three-screen onboarding flow (welcome, age, goal). Call onboardingManager.step() in each screen's useEffect with a step name and index, and call onboardingManager.complete() when the user finishes. This is the core integration for the Paywallo SDK.

```typescript
import { useEffect } from "react";
import { onboardingManager } from "@virex-tech/paywallo-sdk";

function WelcomeScreen({ navigation }) {
  useEffect(() => {
    onboardingManager.step("welcome", 0);
  }, []);

  return (
    <View>
      <Text>Bem-vindo!</Text>
      <Button title="Continuar" onPress={() => navigation.navigate("Age")} />
    </View>
  );
}

function AgeScreen({ navigation }) {
  useEffect(() => {
    onboardingManager.step("age_selection", 1);
  }, []);

  return (
    <View>
      <Text>Qual sua idade?</Text>
      <Button title="Continuar" onPress={() => navigation.navigate("Goal")} />
    </View>
  );
}

function GoalScreen({ navigation }) {
  useEffect(() => {
    onboardingManager.step("goal", 2);
  }, []);

  return (
    <View>
      <Text>Qual seu objetivo?</Text>
      <Button
        title="Finalizar"
        onPress={async () => {
          await onboardingManager.complete();
          navigation.navigate("Paywall");
        }}
      />
    </View>
  );
}
```

--------------------------------

### Obter variante de teste A/B com getVariant (onboarding_flow)

Source: https://paywallo.com.br/docs/flags

Exemplo de uso do método getVariant para um teste com múltiplas variantes, usando switch para renderizar diferentes componentes.

```typescript
import { useState, useEffect } from "react";
import Paywallo from "@virex-tech/paywallo-sdk";

function OnboardingScreen() {
  const [variant, setVariant] = useState<string | null>(null);

  useEffect(() => {
    Paywallo.waitUntilReady()
      .then(() => Paywallo.getVariant("onboarding_flow"))
      .then((result) => {
        setVariant(result.variant);
      });
  }, []);

  // use switch, if/else ou qualquer padrão que preferir
  switch (variant) {
    case "curto":
      return <ShortOnboarding />;
    case "video":
      return <VideoOnboarding />;
    default:
      return <LongOnboarding />;
  }
}
```

--------------------------------

### Rastreamento manual de tela com track()

Source: https://paywallo.com.br/docs/analytics

Sem React Navigation, envie screen_view manualmente chamando track() no callback de exibição de cada tela. Este é o único caminho no Swift nativo.

```typescript
// Sem React Navigation: envie screen_view manualmente
await Paywallo.track("screen_view", {
  properties: { screen_name: "OnboardingStep3" },
});
```

--------------------------------

### Configure PaywalloProvider with PaywalloConfig

Source: https://paywallo.com.br/docs/install

Wrap your app with PaywalloProvider in the root file (App.tsx). The appKey is required and found in Configurações → Apps → SDK Key card. All fields shown are available in PaywalloConfig. The Provider fires $app_installed automatically on mount.

```tsx
import { PaywalloProvider } from "@virex-tech/paywallo-sdk";
import * as Application from "expo-application";

export default function App() {
  return (
    <PaywalloProvider
      config={{
        // Obrigatório: Configurações → Apps → card "SDK Key"
        appKey: "pk_xxxxxxxx",
        // Versão real do app nos eventos (padrão: "unknown")
        appVersion: Application.nativeApplicationVersion ?? undefined,
        // Logs do SDK no console. Use __DEV__ pra não vazar em prod
        debug: __DEV__,
        // "Production" (padrão) ou "Sandbox" pra testar IAP sem cobrar
        environment: "Production",
        // Textos da tela de erro do paywall (todos opcionais)
        errorStrings: { title: "Ops", retry: "Tentar novamente", close: "Fechar" },
        // Placements pré-carregados: present fica quase instantâneo
        preloadPaywalls: ["onboarding"],
        // SKAdNetwork (iOS): conversion value do funil, ligado por padrão.
        // Deixe false se outro SDK do app já for dono do conversion value:
        // o valor é único por app e dois donos corrompem o sinal.
        skan: true,
      }}
    >
      <YourApp />
    </PaywalloProvider>
  );
}
```

--------------------------------

### Configure Paywallo MCP server in .mcp.json

Source: https://paywallo.com.br/docs/mcp

Adds the Paywallo MCP server to the project's .mcp.json file. The Authorization header uses the PAYWALLO_SERVER_KEY environment variable.

```json
{
  "mcpServers": {
    "paywallo": {
      "type": "http",
      "url": "https://paywallo.com.br/api/mcp",
      "headers": {
        "Authorization": "Bearer ${PAYWALLO_SERVER_KEY}"
      }
    }
  }
}
```

--------------------------------

### Configure Paywallo MCP server in Cursor mcp.json

Source: https://paywallo.com.br/docs/mcp

Adds the Paywallo MCP server to the Cursor configuration file at ~/.cursor/mcp.json. The Authorization header uses the PAYWALLO_SERVER_KEY environment variable.

```json
{
  "mcpServers": {
    "paywallo": {
      "url": "https://paywallo.com.br/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:PAYWALLO_SERVER_KEY}"
      }
    }
  }
}
```

--------------------------------

### Configure Paywallo MCP server in Codex config.toml

Source: https://paywallo.com.br/docs/mcp

Adds the Paywallo MCP server to the Codex configuration file at ~/.codex/config.toml. The bearer token is read from the PAYWALLO_SERVER_KEY environment variable.

```toml
[mcp_servers.paywallo]
url = "https://paywallo.com.br/api/mcp"
bearer_token_env_var = "PAYWALLO_SERVER_KEY"
```

--------------------------------

### Use useOnboarding hook for stable step and complete references

Source: https://paywallo.com.br/docs/onboarding-dropout

Use this snippet to access the same step and complete methods via the useOnboarding() hook, which provides stable references. This is useful when you need to call step in a useEffect without worrying about dependency changes.

```typescript
import { useOnboarding } from "@virex-tech/paywallo-sdk";

function AgeScreen() {
  const { step, complete } = useOnboarding();

  useEffect(() => {
    step("age_selection", 1);
  }, [step]);

  // ...
}
```

--------------------------------

### Usar o mesmo userId nos SDKs RevenueCat e Paywallo

Source: https://paywallo.com.br/docs/revenuecat

Chame Purchases.logIn e Paywallo.identify com o mesmo userId antes de mostrar o paywall ou processar a compra. Isso evita que a compra apareça como 'Direto' no painel.

```typescript
import Purchases from "react-native-purchases";
import Paywallo from "@virex-tech/paywallo-sdk";

// Chame os dois ANTES da compra, com o MESMO userId
async function onLoginOrCheckout(userId: string) {
  await Purchases.logIn(userId);
  await Paywallo.identify({ userId });
}
```

--------------------------------

### Register Paywallo MCP server with Claude Code CLI

Source: https://paywallo.com.br/docs/mcp

Registers the Paywallo MCP server with the Claude Code CLI using the HTTP transport and an Authorization header. Requires the PAYWALLO_SERVER_KEY environment variable to be set.

```bash
claude mcp add --transport http paywallo https://paywallo.com.br/api/mcp --header "Authorization: Bearer $PAYWALLO_SERVER_KEY"
```

--------------------------------

### Rastreamento automático de telas com usePaywalloScreenTracking

Source: https://paywallo.com.br/docs/analytics

Registre o hook de navegação uma vez no ponto raiz da navegação para emitir screen_view automaticamente a cada troca de tela. Requer React Navigation.

```typescript
import { usePaywalloScreenTracking } from "@virex-tech/paywallo-sdk";
import { NavigationContainer } from "@react-navigation/native";

export function App() {
  const onStateChange = usePaywalloScreenTracking();

  return (
    <NavigationContainer onStateChange={onStateChange}>
      {/* suas rotas */}
    </NavigationContainer>
  );
}
```

--------------------------------

### Enviar evento com prioridade crítica

Source: https://paywallo.com.br/docs/analytics

Use priority: "critical" para eventos que não podem ser perdidos, como escolha de plano. O evento é enviado imediatamente em lote de 1 e reenviado se a rede falhar. Não use para eventos automáticos, pois o SDK já os envia.

```typescript
// priority: "critical" envia o evento imediatamente (batch-of-1),
// sem aguardar a janela de 25 eventos / 10 segundos.
//
// Use so em evento SEU que nao pode ser perdido. Nao reemita os automaticos
// (lista abaixo) — o SDK ja os envia, e chamar na mao conta duas vezes.
await Paywallo.track("plano_escolhido", {
  properties: {
    plan_id: planId,
    origem: "tela_de_precos",
  },
  priority: "critical",
});
```

--------------------------------

### Gerar id local para fluxo de compra antes do cadastro

Source: https://paywallo.com.br/docs/revenuecat

Para o fluxo 'paga primeiro, cadastra depois', gere um id próprio (ex: UUID salvo no aparelho) antes do paywall e use-o no logIn do RevenueCat e no identify do Paywallo. Guarde esse id na conta do usuário e continue usando o mesmo, pois trocar depois pode quebrar o vínculo com a assinatura.

```typescript
// Ainda sem cadastro? Gere o id você mesmo, antes do paywall,
// e use-o nos dois SDKs. Guarde esse id na conta quando o usuário
// se cadastrar e continue usando o mesmo, sem trocar por outro.
const userId = getOrCreateLocalUserId(); // ex: um UUID salvo no aparelho
await Purchases.logIn(userId);
await Paywallo.identify({ userId });
```