React Native

Questo è l’SDK ufficiale per il checkout React Native di Dodo Payments, @dodopayments/react-native-checkout. Apre il checkout ospitato di Dodo in una vista browser nativa e restituisce un risultato tipizzato. Nota: esiste un pacchetto meno recente e non correlato denominato dodopayments-react-native-sdk (senza scope), con un’API completamente diversa. Questa pagina documenta esclusivamente l’attuale pacchetto ufficiale con scope.

Checkout Sessions API

Crea checkout_url, che questo SDK apre, dal tuo backend.

Mobile Integration Guide

Scopri come si inserisce nel flusso completo dei pagamenti mobile.

L’SDK React Native è un sottile wrapper Turbo Module sui medesimi core nativi Swift e Kotlin. Apre SFSafariViewController su iOS e una Chrome Custom Tab su Android, non conserva alcuna chiave API e non chiama mai direttamente l’API di Dodo. Tutta la logica del checkout viene eseguita nel browser; l’SDK gestisce semplicemente il ciclo di vita della vista e acquisisce l’URL di ritorno.

Questo SDK richiede esclusivamente la New Architecture, React Native 0.76+, iOS 16+ e Android minSdk 24.

Installazione

Install the Package

Android
iOS
Expo

Il pacchetto viene collegato automaticamente e recupera com.dodopayments.api:checkout-android da Maven.

npm i @dodopayments/react-native-checkout

Non è necessaria alcuna configurazione aggiuntiva; la dipendenza nativa viene risolta automaticamente.

npm i @dodopayments/react-native-checkout
cd ios && pod install

Il core Swift è incluso nel pacchetto e viene installato tramite CocoaPods.

Solo build di sviluppo (non Expo Go).

npm i @dodopayments/react-native-checkout

Quindi configura il tuo app.json (vedi Registrare uno schema URL per i callback di seguito).

La tua app deve registrare uno schema URL per ricevere l’URL di ritorno dal checkout.

Android (Gradle)
iOS (Info.plist)
Expo (both platforms)

In android/app/build.gradle:

android/app/build.gradle

android {
    defaultConfig {
        manifestPlaceholders["dodoCallbackScheme"] = "myapp"
    }
}

Sostituisci "myapp" con lo schema della tua app.

In ios/YourApp/Info.plist:

Info.plist

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>myapp</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

Puoi aggiungere anche questo tramite l’interfaccia Info → URL Types di Xcode.

Il plugin di configurazione del pacchetto registra lo scheme per entrambe le piattaforme in prebuild. Passagli un’opzione scheme in app.json:

app.json

{
  "expo": {
    "scheme": "myapp",
    "plugins": [
      [
        "@dodopayments/react-native-checkout",
        { "scheme": "myappcheckout" }
      ]
    ]
  }
}

scheme deve corrispondere a quello che passi come returnUrl (ad esempio myappcheckout://return) e deve essere diverso da expo.scheme. Expo registra già quest’ultimo in MainActivity e riutilizzarlo può indirizzare il ritorno del checkout alla schermata sbagliata.Ricostruisci il progetto nativo dopo aver modificato app.json:

npx expo prebuild --clean

Funziona solo con le development build, non con Expo Go.Se android/app/build.gradle viene gestito manualmente e non contiene un blocco defaultConfig { } standard che il plugin possa individuare, aggiungi tu il placeholder. Consulta la scheda Android qui sopra.

Utilizzo

import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

// Required for iOS's return-URL handling.
Linking.addEventListener('url', ({ url }) => DodoCheckout.handleOpenURL(url));

const result = await DodoCheckout.start({
  checkoutUrl,                          // from your backend's checkout session
  returnUrl: 'myapp://checkout/return', // scheme must be registered (see Installation)
  onEvent: (e) => console.log(e.type),  // logging only
});

switch (result.status) {
  case 'succeeded': showSuccess(result.paymentId); break;
  case 'failed':    showFailure(); break;
  case 'cancelled': dismiss(); break;
  case 'pending':   showPending(); break;
  case 'expired':   showExpired(); break;
}

Inoltro dell’URL di ritorno

Il listener Linking è richiesto per la gestione dell’URL di ritorno su iOS. Su Android, handleOpenURL non esegue alcuna operazione e risolve false, perché il core Android gestisce nativamente il redirect. È sicuro registrare il listener incondizionatamente su entrambe le piattaforme.

import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

Linking.addEventListener('url', ({ url }) => {
  DodoCheckout.handleOpenURL(url);
});

Significato del risultato

result.status è un suggerimento per l’interfaccia utente, non una prova del pagamento. Conferma ogni pagamento dal tuo backend tramite il webhook payment.succeeded / subscription.active.

CheckoutStatus

obbligatorio

Uno tra succeeded, failed, cancelled, pending, expired.

string

Impostato quando l’URL di ritorno ne includeva uno. Visualizzalo nell’interfaccia utente, ma non usarlo per concedere l’accesso. Consulta la sezione Verifica del pagamento qui sotto.

string

Impostato per i checkout degli abbonamenti.

string[]

Impostato quando il checkout include prodotti con chiavi di licenza.

string

Impostato quando il checkout acquisisce un’e-mail.

Record<string, string>

Ogni parametro di query dell’URL di ritorno, alla lettera.

Verifica del pagamento

Webhooks

Dodo Payments contatta il tuo backend quando un pagamento va a buon fine o un abbonamento viene attivato.

Get Payment Detail

Cerca paymentId con la tua secret key per verificarne direttamente lo stato.

Concedi l’accesso dopo che uno di questi ha confermato il pagamento, mai basandoti solo su result.status.

Personalizzazione dell’aspetto

Personalizza la barra degli strumenti, i pulsanti e lo schema di colori del browser di checkout tramite customization su start(...). Le opzioni sono raggruppate per piattaforma perché Custom Tab di Android e SFSafariViewController di iOS espongono controlli nativi differenti. Tutti i campi sono facoltativi; se ometti customization viene utilizzato l’aspetto predefinito di ciascuna piattaforma.

Android — Custom Tab

Colore di sfondo della barra degli strumenti.

Colore della barra di navigazione.

Colore del divisore sopra la barra di navigazione.

'default' | 'back'

default mostra l’icona di sistema “X”; back mostra invece una freccia indietro.

'start' | 'end'

Indica su quale lato della barra degli strumenti viene visualizzato il pulsante di chiusura.

Mostra l’icona di condivisione della barra degli strumenti.

boolean

Mostra il titolo della pagina sotto l’URL nella barra degli strumenti.

boolean

Consente alla barra degli strumenti di nascondersi automaticamente durante lo scorrimento della pagina.

boolean

Mostra “Aggiungi pagina ai segnalibri” nel menu extra.

boolean

Mostra “Scarica pagina” nel menu extra.

'system' | 'light' | 'dark'

Forza l’aspetto chiaro o scuro indipendentemente dall’impostazione di sistema del dispositivo.

iOS — SFSafariViewController

'done' | 'close' | 'cancel'

Etichetta o icona del pulsante di chiusura.

'pageSheet' | 'fullScreen'

pageSheet viene visualizzato come una scheda con chiusura tramite scorrimento; fullScreen copre l’intero schermo.

boolean

Consente alla barra degli strumenti di comprimersi durante lo scorrimento. Visibile solo quando presentationStyle è fullScreen — pageSheet mantiene le barre fissate indipendentemente da questa impostazione.

'system' | 'light' | 'dark'

Forza l’aspetto chiaro o scuro indipendentemente dall’impostazione di sistema del dispositivo.

const result = await DodoCheckout.start({
  checkoutUrl,
  returnUrl: 'myapp://checkout/return',
  customization: {
    android: { toolbarColor: '#6366F1', closeButtonStyle: 'back' },
    ios: { presentationStyle: 'fullScreen', colorScheme: 'dark' },
  },
});

Errori

start rifiuta con un CheckoutError solo in caso di uso improprio o di un errore della piattaforma. Un pagamento annullato o rifiutato restituisce sempre un risultato, non un’eccezione.

INVALID_CHECKOUT_URL: non è un URL di sessione checkout.dodopayments.com.
INVALID_RETURN_URL: non è un URL assoluto valido.
ALREADY_IN_PROGRESS: è già in esecuzione un checkout.
PLATFORM_ERROR: errore imprevisto della piattaforma.

Sessioni abbandonate

Se l’app o il bundle JS viene terminato durante il checkout, la promise va persa, ma il livello nativo mantiene la sessione. Recuperala al mount successivo e riconciliala con il tuo backend.

import { DodoCheckout } from '@dodopayments/react-native-checkout';

const abandoned = await DodoCheckout.getAbandonedSession();
if (abandoned) {
  // reconcile abandoned.sessionId with your backend, then:
  await DodoCheckout.clearAbandonedSession();
}

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

Installazione

Utilizzo

Inoltro dell’URL di ritorno

Significato del risultato

Verifica del pagamento

Webhooks

Get Payment Detail

Personalizzazione dell’aspetto

Errori

Sessioni abbandonate

Correlati

Mobile Integration Guide

Expo Boilerplate

Checkout Sessions API

Mobile Integration Guide

​Installazione

​Utilizzo

​Inoltro dell’URL di ritorno

​Significato del risultato

​Verifica del pagamento

Webhooks

Get Payment Detail

​Personalizzazione dell’aspetto

​Errori

​Sessioni abbandonate

​Correlati

Mobile Integration Guide

Expo Boilerplate

Installazione

Utilizzo

Inoltro dell’URL di ritorno

Significato del risultato

Verifica del pagamento

Personalizzazione dell’aspetto

Errori

Sessioni abbandonate

Correlati