# Raccogliere gli indirizzi fisici e i numeri di telefono Scopri come raccogliere gli indirizzi e i numeri di telefono dei clienti nella tua applicazione mobile con Address Element. # Android Per raccogliere indirizzi completi per la fatturazione o la spedizione, utilizzare [Address Element](https://docs.stripe.com/payments/mobile/address-element.md). Puoi utilizzare Address Element anche per: - Raccogliere i [numeri di telefono](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet.addresselement/-address-launcher/-additional-fields-configuration/index.html) dei clienti - Utilizza il completamento automatico (abilitato per impostazione predefinita) - Precompilare i dati di fatturazione in Payment Element specificando un indirizzo di spedizione Stripe combina le informazioni raccolte sull’indirizzo e sul metodo di pagamento per creare un *PaymentIntent* (API object that represents your intent to collect payment from a customer, tracking charge attempts and payment state changes throughout the process). ![Esempi di una procedura di pagamento in cui un utente seleziona l'opzione Aggiungi indirizzo di spedizione. Poi l'utente viene indirizzato a una nuova schermata per aggiungere l'indirizzo di spedizione in un modulo. Mentre digita l'indirizzo, può scegliere tra i suggerimenti di completamento automatico.](https://b.stripecdn.com/docs-statics-srv/assets/android-overview.414fc754c90afc0ec42840299c12022d.png) ## Configura Stripe [Lato server] [Lato client] Innanzitutto, devi creare un account Stripe. [Registrati ora](https://dashboard.stripe.com/register). L’[SDK per Android di Stripe](https://github.com/stripe/stripe-android) è open source e [completamente documentato](https://stripe.dev/stripe-android/). Per installare l’SDK, aggiungi `stripe-android` al blocco `dependencies` del tuo file [app/build.gradle](https://developer.android.com/studio/build/dependencies): #### Kotlin ```kotlin plugins { id("com.android.application") } android { ... } dependencies { // ... // Stripe Android SDK implementation("com.stripe:stripe-android:23.18.0") // Include the financial connections SDK to support US bank account as a payment method implementation("com.stripe:financial-connections:23.18.0") } ``` > Per ulteriori informazioni sulla versione più recente e su quelle precedenti dell’SDK, consulta la pagina [Releases](https://github.com/stripe/stripe-android/releases) su GitHub. Per ricevere una notifica quando viene pubblicata una nuova versione, [imposta il controllo delle versioni per il repository](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository). Configura l’SDK con la tua [chiave pubblicabile](https://dashboard.stripe.com/apikeys) di Stripe in modo che possa inviare le richieste all’API Stripe, ad esempio nella sottoclasse `Application`: #### Kotlin ```kotlin import com.stripe.android.PaymentConfiguration class MyApp : Application() { override fun onCreate() { super.onCreate() PaymentConfiguration.init( applicationContext, "<>" ) } } ``` > Usa le [chiavi di test](https://docs.stripe.com/keys.md#obtain-api-keys) durante i test e le chiavi della [modalità live](https://docs.stripe.com/keys.md#test-live-modes) quando pubblichi l’app. ## Impostare i suggerimenti di completamento automatico dell'indirizzo Stripe fornisce automaticamente suggerimenti di completamento automatico quando il cliente seleziona un paese supportato. Non sono necessari ulteriori passaggi di integrazione. > Utilizzando il completamento automatico, accetti di rispettare la [Politica sull’uso accettabile di Google Maps Platform](https://cloud.google.com/maps-platform/terms/aup). In caso di violazione di queste norme, Stripe potrebbe disabilitare il completamento automatico o adottare altre misure necessarie. ## Configurare Address Element Puoi configurare Address Element con informazioni quali la visualizzazione dei valori predefiniti, l’impostazione dei Paesi consentiti, la personalizzazione dell’aspetto e così via. Per l’elenco completo delle opzioni di configurazione, fai riferimento a [AddressLauncher.Configuration](https://github.com/stripe/stripe-android/blob/master/paymentsheet/src/main/java/com/stripe/android/paymentsheet/addresselement/AddressLauncher.kt#L72). ```kotlin val addressConfiguration = AddressLauncher.Configuration.Builder() .additionalFields( AddressLauncher.AdditionalFieldsConfiguration( phone = AddressLauncher.AdditionalFieldsConfiguration.FieldConfiguration.REQUIRED ) ) .allowedCountries(setOf("US", "CA", "GB")) .title("Shipping Address") .build() ``` L’Address Element mostra inizialmente un unico campo per l’indirizzo. Man mano che il cliente digita, vengono visualizzati suggerimenti corrispondenti direttamente nel campo. Quando il cliente seleziona un suggerimento, l’Address Element compila automaticamente il modulo dell’indirizzo. ## Recuperare i dati relativi all'indirizzo Recupera i dettagli dell’indirizzo creando un’istanza di `AddressLauncher` nel metodo del ciclo di vita `onCreate` di `Activity` o `Fragment` e creando un metodo di callback che implementi l’interfaccia `AddressLauncherResultCallback`. ```kotlin private lateinit var addressLauncher: AddressLauncher private var shippingDetails: AddressDetails? = null override fun onCreate(savedInstanceState: Bundle?) { addressLauncher = AddressLauncher(this, ::onAddressLauncherResult) } private fun onAddressLauncherResult(result: AddressLauncherResult) { // TODO: Handle result and update your UI when (result) { is AddressLauncherResult.Succeeded -> { shippingDetails = result.address } is AddressLauncherResult.Canceled -> { // TODO: Handle cancel } } } ``` Lo stato del parametro `AddressLauncherResult` può essere `Succeeded` or `Canceled`. Scopri di più sui [dettagli dell’implementazione](https://github.com/stripe/stripe-android/blob/master/paymentsheet/src/main/java/com/stripe/android/paymentsheet/addresselement/AddressLauncherResult.kt). > Stripe richiede di creare un’istanza di `AddressLauncher` durante l’evento del ciclo di vita `onCreate` e non dopo. In caso contrario, il callback non potrà essere registrato correttamente e l’app si arresterà in modo anomalo. ## Presentare Address Element Presenta l’Address Element utilizzando l’utilità di avvio degli indirizzi e la configurazione dei passaggi precedenti. ```kotlin addressLauncher.present( publishableKey = publishableKey, configuration = addressConfiguration ) ``` ## Optional: Precompilare gli indirizzi di spedizione in Payment Element Se utilizzi Payment Element su dispositivo mobile, imposta [PaymentSheet.Configuration.shippingDetails](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/index.html) sull’indirizzo raccolto dall’elemento indirizzo. Quando `shippingDetails` è compilato, l’indirizzo di fatturazione viene pre-compilato per gli utenti e vedono una casella di controllo **L’indirizzo di fatturazione è lo stesso dell’indirizzo di spedizione**. I PaymentIntents confermati con `shippingDetails` compilato hanno anche la proprietà [shipping](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-shipping) intent compilata quando il PaymentIntent è confermato ```kotlin val configuration = PaymentSheet.Configuration.Builder("Example, Inc.") // ... .shippingDetails(shippingDetails) .build() ``` ## Optional: Personalizza l'aspetto Ora che hai aggiunto Address Element alla tua app, puoi personalizzarne l’aspetto per adattarlo al design del resto della tua app. Puoi configurare l’aspetto con l’[API Appearance](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=android) utilizzando [AddressLauncher.Configuration.appearance](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet.addresselement/-address-launcher/-configuration/index.html). ## Optional: Impostare i dati di fatturazione predefiniti Per impostare i valori predefiniti per i dettagli di addebito raccolti nella scheda di pagamento, configura la proprietà `defaultBillingDetails`. `PaymentSheet` precompila i campi della scheda con i valori che fornisci. #### Kotlin ```kotlin val address = PaymentSheet.Address(country = "US") val billingDetails = PaymentSheet.BillingDetails( address = address, email = "foo@bar.com" ) val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "Merchant, Inc.") .defaultBillingDetails(billingDetails) .build() ``` ## Optional: Personalizzare la raccolta dei dati per gli addebiti ### Configura la raccolta dei dati di fatturazione Usa `BillingDetailsCollectionConfiguration` per specificare come vuoi raccogliere i dettagli di addebito in PaymentSheet. Puoi acquisire il nome, l’indirizzo email, il numero di telefono e l’indirizzo del cliente. La raccolta dell’indirizzo completo include il completamento automatico fornito da Stripe per i Paesi supportati, senza necessità di configurazioni aggiuntive. > Utilizzando il completamento automatico, accetti di rispettare la [Politica sull’uso accettabile di Google Maps Platform](https://cloud.google.com/maps-platform/terms/aup). In caso di violazione di queste norme, Stripe potrebbe disabilitare il completamento automatico o adottare altre misure necessarie. Se vuoi associare i dati di fatturazione predefiniti all’oggetto PaymentMethod anche quando tali campi non sono raccolti nell’interfaccia utente, imposta `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` su `true`. #### Kotlin ```kotlin val billingDetails = PaymentSheet.BillingDetails( email = "foo@bar.com" ) val billingDetailsCollectionConfiguration = BillingDetailsCollectionConfiguration( attachDefaultsToPaymentMethod = true, name = BillingDetailsCollectionConfiguration.CollectionMode.Always, email = BillingDetailsCollectionConfiguration.CollectionMode.Never, address = BillingDetailsCollectionConfiguration.AddressCollectionMode.Full, ) val configuration = PaymentSheet.Configuration.Builder(merchantDisplayName = "Merchant, Inc.") .defaultBillingDetails(billingDetails) .billingDetailsCollectionConfiguration(billingDetailsCollectionConfiguration) .build() ``` > Rivolgiti al tuo consulente legale per sapere quali sono le leggi applicabili alla raccolta di informazioni. Richiedi i numeri di telefono solo se necessari per la transazione. ## Optional: Personalizza i Paesi per il completamento automatico Per impostazione predefinita, i suggerimenti del completamento automatico sono disponibili per tutti i Paesi supportati da Stripe. Per limitare il completamento automatico a Paesi specifici, specifica i relativi codici Paese a due lettere tramite `autocompleteCountries`: ```kotlin val addressConfiguration = AddressLauncher.Configuration.Builder() .autocompleteCountries(setOf("US", "CA", "GB")) .build() ``` Questa impostazione controlla solo i Paesi per i quali vengono visualizzati i suggerimenti del completamento automatico. Non limita i Paesi che i clienti possono selezionare nel modulo dell’indirizzo. Per limitare la selezione dei Paesi, utilizza `allowedCountries`. Quando il completamento automatico non è disponibile, i clienti possono inserire manualmente il proprio indirizzo.