Passa al contenuto principale
Tutti i sistemi operativiNovitàv1
Accedi
Web SDK

SDK Web en un WebView móvil

Implementare un checkout web per il commerciante all'interno di un WebView mobile, mantenendo le callback di DEUNA, l'autenticazione esterna, i confini di sicurezza e il comportamento responsive.

Ultimo aggiornamento: October 17, 2026
In questa pagina

Utilizzare un WebView personalizzato solo quando la vostra applicazione deve ospitare un processo di checkout esistente e di proprietà del commerciante. Per una nuova integrazione mobile, è preferibile utilizzare il metodo standard. iOS, Androido Reazione nativo SDK; questi SDK implementano già il ponte DEUNA WebView e il ciclo di vita delle azioni esterne.

Architettura#

Diagramma di sequenza
1Native app2Merchant checkoutWebView3DEUNA Web SDK43DS / APM surfaceLoad allow-listed HTTPScheckout URLInitialize and open widgetCallback oropenExternalPopupValidated JSON bridgemessageOpen approved external URLClose or returnResume and reconcile
Commerciante o clienteDEUNAProvider o processore
01 · load
Checkout sicuro e affidabile
Utilizzare HTTPS e un'origine del commerciante autorizzata.
02 · bridge
Validare i messaggi
Accettare uno schema minimale e versionato, solo dalla pagina prevista.
03 · redirect
Gestire le azioni esterne
Visualizzare gli URL di 3DS e APM in un browser approvato o in una WebView secondaria.
04 · reconcile
Confermare lo stato dell'ordine
Considerare i resi e le chiusure come ambigue fino a quando il backend non le verifica.

Vedere il modello wrapper WebView#

Questa procedura dettagliata mostra un checkout web del commerciante caricato all'interno di un WebView iOS. Il wrapper nativo scambia messaggi con la pagina di pagamento mentre DEUNA Web SDK rende l'esperienza di pagamento:

WebView wrapper example using a merchant checkout page and native message bridge.

Il video mostra il modello di presentazione. I dettagli dell'interfaccia utente possono cambiare; utilizzare l'architettura, i limiti di sicurezza e i requisiti della piattaforma riportati di seguito come contratto di implementazione.

Requisiti per la WebView#

CapacitàPerché è necessario
JavaScript e storage del DOMIl checkout ospitato e l'SDK richiedono l'esecuzione nel browser e lo storage della sessione.
Intercettazione di nuove finestreI flussi 3DS e APM possono utilizzare window.open.
Lista di navigazione autorizzataPrevenire che la WebView del checkout diventi un browser generico.
Ponte di messaggi bidirezionaleInviare messaggi di completamento, errore, chiusura e ciclo di vita.
Gestione del ciclo di vita dell'appMantenere lo stato durante il backgrounding e l'autenticazione esterna.
Download o condivisione, se utilizzatoI flussi di voucher possono generare un file o un riferimento scaricabile.

Definire un ponte minimo#

Codice in esecuzione nella pagina di checkout del commercianteJavaScript
type NativeMessage = {
  version: 1;
  type: 'success' | 'error' | 'closed' | 'event';
  widget: 'payment' | 'elements' | 'voucher' | 'nextAction';
  data?: unknown;
};

function postToNative(message: NativeMessage) {
  const body = JSON.stringify(message);
  window.webkit?.messageHandlers.deunaPayment?.postMessage(body); // iOS
  window.deunaPayment?.postMessage(body);                         // Android
  window.ReactNativeWebView?.postMessage(body);                   // React Native
}

Nel limite nativo, analizzare JSON con uno schema rigoroso, rifiutare versioni e tipi di messaggi sconosciuti, limitare la dimensione del messaggio e ignorare i messaggi provenienti da una pagina di livello superiore inaspettata. Non esporre un dispatcher nativo generico a JavaScript.

Trasmettere risultati SDK#

JavaScript
await DeunaSDK.initPaymentWidget({
  orderToken,
  callbacks: {
    onSuccess: (data) => postToNative({version: 1, type: 'success', widget: 'payment', data}),
    onError: (data) => postToNative({version: 1, type: 'error', widget: 'payment', data}),
    onClosed: (action) => postToNative({version: 1, type: 'closed', widget: 'payment', data: {action}}),
    onEventDispatch: (event) => postToNative({
      version: 1,
      type: 'event',
      widget: 'payment',
      data: {event},
    }),
  },
});

Trasmettere solo i campi necessari all'applicazione nativa. Non è necessario collegare token di ordine, token di wallet, dati di carta, oggetti cliente completi o payload di eventi grezzi arbitrari.

Finestre e reindirizzamenti esterni#

Il Web SDK emette eventi di ciclo di vita per popup esterni supportati. La tua WebView deve intercettare window.open o richieste di nuove finestre e presentare la destinazione senza segnalare erroneamente che è stata immediatamente chiusa.

  • Consentire solo https URL il cui host corrisponda alle destinazioni di autenticazione o pagamento approvate.
  • Preferire una superficie del browser isolata per i contenuti di terze parti; non iniettare il ponte del commerciante in una pagina dell'emittente o del fornitore.
  • Tracciare la superficie esterna in modo indipendente dalla WebView di checkout.
  • Al termine della transazione o al ritorno, riprendere il processo di checkout e recuperare lo stato dell'ordine.
  • Non sopprimere globalmente gli errori di timeout. Un timeout può indicare un'azione incompleta; risolvere il problema e mostrare un percorso di recupero appropriato.

I repository SDK includono wrapper di riferimento mantenuti per Examples/checkout-web-wrapper per iOS e examples/checkout-web-wrapper per Android.

Controllo della piattaforma#

iOS · WKWebViewNavigazione e messaggi di script

Abilitare JavaScript per la configurazione di checkout affidabile, registrare un nome specifico e WKScriptMessageHandler, validare la navigazione di livello superiore in WKNavigationDelegatee implementare WKUIDelegate Gestione di nuove finestre. Rimuovere i gestori di script quando il controller viene eliminato per evitare di mantenere il ponte.

Android · WebViewNavigazione e creazione di finestre

Abilitare JavaScript e la memorizzazione nel browser WebView solo per il processo di checkout, utilizzare un'interfaccia JavaScript limitata e validare gli URL. WebViewClient, gestendo nuove finestre tramite WebChromeClient o una superficie secondaria controllata. Disabilita l'accesso a file e contenuti a meno che la tua applicazione non ne abbia esplicitamente bisogno.

React Native · react-native-webviewCiclo di vita dei messaggi e finestre

Uso onMessage, onShouldStartLoadWithRequest, e la callback per la nuova finestra supportata. Mantenere il componente principale di checkout attivo mentre la finestra esterna è visibile. L'SDK React Native di DEUNA, già disponibile, implementa questo controllo ed è preferibile per le nuove integrazioni.

Presentazione responsive e accessibile#

  • Rispettare lo spazio sicuro (safe-area insets) e la tastiera sullo schermo.
  • Utilizzare l'intera larghezza disponibile e l'altezza dinamica dello schermo; evitare un WebView di dimensioni fisse.
  • Mantenere i controlli di chiusura nativi al di fuori del contenuto di pagamento, ma accessibili alle tecnologie assistive.
  • Annunciare la navigazione e gli errori, e ripristinare il focus dopo la chiusura di una superficie esterna.
  • Testare la rotazione, lo split-screen, il testo di grandi dimensioni, i lettori di schermo, le reti lente e lo stato di background dell'app.

Matrice di test#

  • Successo, rifiuto e chiusura del pagamento da parte del cliente.
  • 3DS senza attriti e problematiche.
  • Successo, cancellazione e timeout del provider per l'APM.
  • Finestra esterna chiusa dal cliente.
  • App in background e ripresa successivamente.
  • Perdita di connessione prima e dopo la trasmissione.
  • Navigazioni non attendibili e messaggi di bridge malformati vengono rifiutati.
  • Lo stato del backend è corretto dopo ogni risultato ambiguo del client.
SDK nativiPreferire le integrazioni con la piattaforma mantenute.Prossimo passoContinuare con 3DS e redirect in modo sicuro.Risposte dell'SDKNormalizzare i risultati del bridge.