# 收集物理地址和电话号码

了解如何使用 Address Element 在移动端应用中收集客户地址和电话号码。

# iOS (UIKit)

> This is a iOS (UIKit) for when payment-ui is mobile and platform is ios. View the full page at https://docs.stripe.com/payments/mobile/collect-addresses?payment-ui=mobile&platform=ios.

要收集完整的地址以进行计费或送货，请使用 [Address Element](https://docs.stripe.com/payments/mobile/address-element.md)。

还可以使用 Address Element 执行以下作：

- 收集客户[电话号码](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/addressviewcontroller/addressdetails/phone)
- 使用自动完成功能（在 iOS 中默认启用）
- 通过传入收货地址在 Payment Element 中预填充账单信息

Stripe 将收集的地址信息和支付方式合在一起来创建 *PaymentIntent* (API object that represents your intent to collect payment from a customer, tracking charge attempts and payment state changes throughout the process)。
![用户选择“添加收货地址”选项的结账流程示例。然后，他们被带到一个新的界面，在这里将他们的收货地址添加到表单中。当他们输入地址时，系统会显示自动完成建议供用户选择。](https://b.stripecdn.com/docs-statics-srv/assets/ios-overview.4e83bb4e46fd7d131b5c4ff8abee27ea.png)

## 设置 Stripe [服务器端] [客户端]

首先，您需要有 Stripe 账户。[立即注册](https://dashboard.stripe.com/register)。

[Stripe iOS SDK](https://github.com/stripe/stripe-ios) 是开源的，[有完整的文档](https://stripe.dev/stripe-ios/index.html)，并且与支持 iOS 13 或更高版本操作系统的应用程序兼容。

#### Swift Package Manager

要安装 SDK，按这些步骤进行：

1. 在 Xcode 中，选择**文件** > **添加工具包依赖…**并输入 `https://github.com/stripe/stripe-ios-spm` 作为仓库 URL。
1. 从我们的[发布页面](https://github.com/stripe/stripe-ios/releases)选择最新的版本号。
1. 将 **StripePaymentSheet** 产品添加到[您的目标应用程序](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app)。

#### CocoaPods

1. 如果您还没有[CocoaPods](https://guides.cocoapods.org/using/getting-started.html)，请安装其最新版本。
1. 如果您目前没有 [Podfile](https://guides.cocoapods.org/syntax/podfile.html)，请运行以下命令创建一个：
   ```bash
   pod init
   ```
1. 将这一行代码添加到您的 `Podfile`：
   ```podfile
   pod 'StripePaymentSheet'
   ```
1. 运行以下命令：
   ```bash
   pod install
   ```
1. 今后，一定记得用 `.xcworkspace` 文件来打开您在 Xcode 中的项目，不要使用 `.xcodeproj` 文件。
1. 将来，要更新到 SDK 的最新版本，运行：
   ```bash
   pod update StripePaymentSheet
   ```

#### Carthage

1. 如果您还没有[Carthage](https://github.com/Carthage/Carthage#installing-carthage)，请安装其最新版本。
1. 将这一行代码添加到您的 `Cartfile`。
   ```cartfile
   github "stripe/stripe-ios"
   ```
1. 按照 [Carthage 安装说明](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos)进行。确保嵌入[这里](https://github.com/stripe/stripe-ios/tree/master/StripePaymentSheet/README.md#manual-linking)所列的所有必要框架。
1. 将来，要更新到 SDK 的最新版本，运行以下命令即可：
   ```bash
   carthage update stripe-ios --platform ios
   ```

#### 手动框架

1. 前往我们的 [GitHub 发布页面](https://github.com/stripe/stripe-ios/releases/latest)，下载并解压缩 **Stripe.xcframework.zip**。
1. 将 **StripePaymentSheet.xcframework** 拖拽到您的 Xcode 项目中 **General**（常规）设置的 **Embedded Binaries**（嵌入式二进制文件）部分。一定要选择 **Copy items if needed**（需要时复制项目）。
1. 为[这里](https://github.com/stripe/stripe-ios/tree/master/StripePaymentSheet/README.md#manual-linking)所列的所有必要框架重复第 2 步。
1. 将来，要更新到 SDK 的最新版本，重复第 1-3 步。

> 有关最新 SDK 发布及过往版本的详细信息，请查看 GitHub 上的[发布](https://github.com/stripe/stripe-ios/releases)页面。要想在新版本发布时接收通知，请[查看仓库的发布](https://help.github.com/en/articles/watching-and-unwatching-releases-for-a-repository#watching-releases-for-a-repository)。

在应用程序启动时使用您的 Stripe [公钥](https://dashboard.stripe.com/test/apikeys) 配置 SDK。这样可使您的应用程序向 Stripe API 发出请求。

#### Swift

```swift
import UIKitimportStripePaymentSheet

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {StripeAPI.defaultPublishableKey = "<<YOUR_PUBLISHABLE_KEY>>"
        // do any other necessary launch configuration
        return true
    }
}
```

> 测试时使用您的[测试密钥](https://docs.stripe.com/keys.md#obtain-api-keys)，发布应用时使用[真实模式](https://docs.stripe.com/keys.md#test-live-modes)密钥。

## 设置地址自动完成建议

iOS 系统会默认启用自动完成功能。

## 配置 Address Element

可以使用显示默认值、设置允许的国家/地区、自定义外观等详细信息来配置 Address Element。有关配置选项的完整列表，请参阅 [AddressViewController.Configuration](https://github.com/stripe/stripe-ios/blob/address-element-private-beta-2/Stripe/AddressViewController%2BConfiguration.swift#L72-L162)。

```swift
let addressConfiguration = AddressViewController.Configuration(
  additionalFields: .init(phone: .required),
  allowedCountries: ["US", "CA", "GB"],
  title: "Shipping Address"
)
```

## 检索地址详情

通过满足 `AddressViewControllerDelegate` 并使用 [addressViewControllerDidFinish](https://github.com/stripe/stripe-ios/blob/address-element-private-beta-2/Stripe/AddressViewController.swift#L19) 关闭视图控制器来检索地址详细信息。地址的值是有效的[地址](https://github.com/stripe/stripe-ios/blob/8399ea6cfe4e32190238375882e0a793b483d426/Stripe/AddressViewController%2BConfiguration.swift#L16-L36)或空。

```swift
extension MyViewController: AddressViewControllerDelegate {
    func addressViewControllerDidFinish(_ addressViewController: AddressViewController, with address: AddressViewController.AddressDetails?) {
        addressViewController.dismiss(animated: true)
        self.addressDetails = address
    }
}

```

## 显示 Address Element

使用以上步骤中的地址配置和委托创建 [AddressViewController](https://github.com/stripe/stripe-ios/blob/address-element-private-beta-2/Stripe/AddressViewController.swift#L26)。您可以将其显示在导航控制器中，也可以将其推送到导航控制器上。

```swift
self.addressViewController = AddressViewController(configuration: addressConfiguration, delegate: self)
let navigationController = UINavigationController(rootViewController: addressViewController)

present(navigationController, animated: true)
```

## Optional: 在 Payment Element 中预填充收货地址

如果使用移动端 Payment Element，请将[PaymentSheet.Configuration.shippingDetails](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/paymentsheet/configuration-swift.struct/shippingdetails/) 设置为地址元素收集的地址。当 `shippingDetails` 被填入时，用户的账单地址会被预填，他们会看到一个**账单地址与收货地址相同**的复选框。当确认 PaymentIntent 时，已填充 `shippingDetails` 的已确认 PaymentIntents 也会填充 [shipping](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-shipping) intent 属性。

```swift
var configuration = PaymentSheet.Configuration()
// ...
configuration.shippingDetails = { [weak self] in
    return self?.addressDetails
}

```

## Optional: 自定义外观

现在您已将 Address Element 添加到您的应用中，您可以自定义其外观以匹配应用其余部分的设计。您可以使用 [外观 API](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=ios) 通过 [AddressViewController.Configuration.appearance](https://github.com/stripe/stripe-ios/blob/address-element-private-beta-2/Stripe/AddressViewController%2BConfiguration.swift#L149) 来配置外观。

## Optional: 设置默认账单详情

要为支付表单中收集的账单详情设置默认值，请配置 `defaultBillingDetails` 属性。`paymentSheet` 会用您提供的值预先填充其字段。

```swift
var configuration = PaymentSheet.Configuration()
configuration.defaultBillingDetails.address.country = "US"
configuration.defaultBillingDetails.email = "foo@bar.com"
```

## Optional: 自定义账单地址信息的收集

用 `billingDetailsCollectionConfiguration` 来指定您希望如何在支付表单中收集账单详情。

可以收集客户的姓名、邮件地址、电话号码和地址。

如果您只想通过支付方式获得所需的账单详情，请将 `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` 设置为 true。在这种情况下，`PaymentSheet.Configuration.defaultBillingDetails` 被设置为支付方式的 [billing details](https://docs.stripe.com/api/payment_methods/object.md?lang=node#payment_method_object-billing_details)。

如果您希望收集支付方式非必需的额外账单详情，请将 `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` 设置为 false。在这种情况下，通过 `PaymentSheet` 收集的账单详情被设置为支付方式的账单详情。

```swift
var configuration = PaymentSheet.Configuration()
configuration.defaultBillingDetails.email = "foo@bar.com"
configuration.billingDetailsCollectionConfiguration.name = .always
configuration.billingDetailsCollectionConfiguration.email = .never
configuration.billingDetailsCollectionConfiguration.address = .full
configuration.billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod = true
```

> 请咨询律师，了解与收集信息有关的法律。仅在需要收集号码来完成交易时，才收集手机号码。


# iOS (SwiftUI)

> This is a iOS (SwiftUI) for when payment-ui is mobile and platform is plugins. View the full page at https://docs.stripe.com/payments/mobile/collect-addresses?payment-ui=mobile&platform=plugins.

要收集完整的地址以进行计费或送货，请在 SwiftUI 中使用 [Address Element](https://docs.stripe.com/payments/mobile/address-element.md)。

还可以使用 Address Element 执行以下作：

- 收集客户[电话号码](https://stripe.dev/stripe-ios/stripepaymentsheet/documentation/stripepaymentsheet/addresselement/addressdetails/phone)
- 使用自动完成（在 iOS 中默认启用）
- 通过传入收货地址在 Payment Element 中预填充账单信息

Stripe 将收集的地址信息和支付方式合在一起来创建 *PaymentIntent* (API object that represents your intent to collect payment from a customer, tracking charge attempts and payment state changes throughout the process)。
![用户选择“添加配送地址”选项的结账流程示例。用户将被引导至新页面，在表单中填写配送地址。自动完成会为用户提供可选的建议选项。](https://b.stripecdn.com/docs-statics-srv/assets/ios-overview.4e83bb4e46fd7d131b5c4ff8abee27ea.png)

## 设置 Stripe [服务器端] [客户端]

首先，您需要有 Stripe 账户。[立即注册](https://dashboard.stripe.com/register)。

[Stripe iOS SDK](https://github.com/stripe/stripe-ios) 是开源的，[有完整的文档](https://stripe.dev/stripe-ios/index.html)，并且与支持 iOS 13 或更高版本操作系统的应用程序兼容。

#### Swift Package Manager

要安装 SDK，按这些步骤进行：

1. 在 Xcode 中，选择**文件** > **添加工具包依赖…**并输入 `https://github.com/stripe/stripe-ios-spm` 作为仓库 URL。
1. 从我们的[发布页面](https://github.com/stripe/stripe-ios/releases)选择最新的版本号。
1. 将 **StripePaymentSheet** 产品添加到[您的目标应用程序](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app)。

#### CocoaPods

1. 如果您还没有[CocoaPods](https://guides.cocoapods.org/using/getting-started.html)，请安装其最新版本。
1. 如果您目前没有 [Podfile](https://guides.cocoapods.org/syntax/podfile.html)，请运行以下命令创建一个：
   ```bash
   pod init
   ```
1. 将这一行代码添加到您的 `Podfile`：
   ```podfile
   pod 'StripePaymentSheet'
   ```
1. 运行以下命令：
   ```bash
   pod install
   ```
1. 今后，一定记得用 `.xcworkspace` 文件来打开您在 Xcode 中的项目，不要使用 `.xcodeproj` 文件。
1. 将来，要更新到 SDK 的最新版本，运行：
   ```bash
   pod update StripePaymentSheet
   ```

#### Carthage

1. 如果您还没有[Carthage](https://github.com/Carthage/Carthage#installing-carthage)，请安装其最新版本。
1. 将这一行代码添加到您的 `Cartfile`。
   ```cartfile
   github "stripe/stripe-ios"
   ```
1. 按照 [Carthage 安装说明](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos)进行。确保嵌入[这里](https://github.com/stripe/stripe-ios/tree/master/StripePaymentSheet/README.md#manual-linking)所列的所有必要框架。
1. 将来，要更新到 SDK 的最新版本，运行以下命令即可：
   ```bash
   carthage update stripe-ios --platform ios
   ```

#### 手动框架

1. 前往我们的 [GitHub 发布页面](https://github.com/stripe/stripe-ios/releases/latest)，下载并解压缩 **Stripe.xcframework.zip**。
1. 将 **StripePaymentSheet.xcframework** 拖拽到您的 Xcode 项目中 **General**（常规）设置的 **Embedded Binaries**（嵌入式二进制文件）部分。一定要选择 **Copy items if needed**（需要时复制项目）。
1. 为[这里](https://github.com/stripe/stripe-ios/tree/master/StripePaymentSheet/README.md#manual-linking)所列的所有必要框架重复第 2 步。
1. 将来，要更新到 SDK 的最新版本，重复第 1-3 步。

> 有关最新 SDK 发布及过往版本的详细信息，请查看 GitHub 上的[发布](https://github.com/stripe/stripe-ios/releases)页面。要想在新版本发布时接收通知，请[查看仓库的发布](https://help.github.com/en/articles/watching-and-unwatching-releases-for-a-repository#watching-releases-for-a-repository)。

在应用程序启动时使用您的 Stripe [公钥](https://dashboard.stripe.com/test/apikeys) 配置 SDK。这样可使您的应用程序向 Stripe API 发出请求。

#### Swift

```swift
import UIKitimportStripePaymentSheet

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {StripeAPI.defaultPublishableKey = "<<YOUR_PUBLISHABLE_KEY>>"
        // do any other necessary launch configuration
        return true
    }
}
```

> 测试时使用您的[测试密钥](https://docs.stripe.com/keys.md#obtain-api-keys)，发布应用时使用[真实模式](https://docs.stripe.com/keys.md#test-live-modes)密钥。

## 设置地址自动完成建议

iOS 系统会默认启用自动完成功能。

## 配置 Address Element

您可以使用详细信息配置地址元素，例如显示默认值、设置允许的国家/地区、调整外观样式等。请参阅 `AddressElement.Configuration`，获取完整的配置选项列表。

```swift
var configuration = AddressElement.Configuration()
configuration.allowedCountries = ["US", "CA", "GB", "AU"]
configuration.buttonTitle = "Save Address"
```

## 显示 Address Element

```swift
import SwiftUI
import StripePaymentSheet

struct MyView: View {
    @State private var showingAddressElement = false
    @State private var collectedAddress: AddressElement.AddressDetails?
    
    var body: some View {
        VStack {
            Button("Collect Address") {
                showingAddressElement = true
            }
            .sheet(isPresented: $showingAddressElement) {
                AddressElement(
                    address: $collectedAddress,
                    configuration: configuration
                )
            }
            
            // Display collected address
            if let address = collectedAddress {
                AddressView(address: address)
            }
        }
    }
} 
```

## 检索地址详情

当客户完成或取消地址填写时，地址元素会自动更新绑定的 `address` 变量：

```swift
struct AddressView: View {
    let address: AddressElement.AddressDetails
    
    var body: some View {
        VStack(alignment: .leading, spacing: 8) {
            Text("Collected Address:")
                .font(.headline)
            
            if let name = address.name {
                Text("Name: \(name)")
            }
            
            Text("Address: \(address.address.line1)")
            
            if let city = address.address.city {
                Text("City: \(city)")
            }
            
            Text("Country: \(address.address.country)")
            
            if let phone = address.phone {
                Text("Phone: \(phone)")
            }
        }
        .padding()
    }
}
```

## Optional: 自定义外观

现在您已将地址元素集成到应用中，接下来可自定义其外观，使其与整体应用设计风格保持一致。您可以使用外观 API 通过 `AddressElement.Configuration.appearance` 配置外观。

## Optional: 设置默认账单详情

要为支付表单中收集的账单详情设置默认值，请配置 `defaultBillingDetails` 属性。`paymentSheet` 会用您提供的值预先填充其字段。

```swift
var configuration = PaymentSheet.Configuration()
configuration.defaultBillingDetails.address.country = "US"
configuration.defaultBillingDetails.email = "foo@bar.com"
```

## Optional: 自定义账单地址信息的收集

用 `billingDetailsCollectionConfiguration` 来指定您希望如何在支付表单中收集账单详情。

可以收集客户的姓名、邮件地址、电话号码和地址。

如果您只想通过支付方式获得所需的账单详情，请将 `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` 设置为 true。在这种情况下，`PaymentSheet.Configuration.defaultBillingDetails` 被设置为支付方式的 [billing details](https://docs.stripe.com/api/payment_methods/object.md?lang=node#payment_method_object-billing_details)。

如果您希望收集支付方式非必需的额外账单详情，请将 `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` 设置为 false。在这种情况下，通过 `PaymentSheet` 收集的账单详情被设置为支付方式的账单详情。

```swift
var configuration = PaymentSheet.Configuration()
configuration.defaultBillingDetails.email = "foo@bar.com"
configuration.billingDetailsCollectionConfiguration.name = .always
configuration.billingDetailsCollectionConfiguration.email = .never
configuration.billingDetailsCollectionConfiguration.address = .full
configuration.billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod = true
```

> 请咨询律师，了解与收集信息有关的法律。仅在需要收集号码来完成交易时，才收集手机号码。


# Android

> This is a Android for when payment-ui is mobile and platform is android. View the full page at https://docs.stripe.com/payments/mobile/collect-addresses?payment-ui=mobile&platform=android.

要收集完整的地址以进行计费或送货，请使用 [Address Element](https://docs.stripe.com/payments/mobile/address-element.md)。

还可以使用 Address Element 执行以下作：

- 收集客户[电话号码](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet.addresselement/-address-launcher/-additional-fields-configuration/index.html)
- 启用[自动完成功能](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet.addresselement/-address-launcher/-configuration/index.html)
- 通过传入收货地址在 Payment Element 中预填充账单信息

Stripe 将收集的地址信息和支付方式合在一起来创建 *PaymentIntent* (API object that represents your intent to collect payment from a customer, tracking charge attempts and payment state changes throughout the process)。
![用户选择“添加收货地址”选项的结账流程示例。然后，他们被带到一个新的界面，将他们的收货地址添加到一个表单中（他们会在键入地址时看到自动完成建议）。](https://b.stripecdn.com/docs-statics-srv/assets/android-overview.6061212dc737aa700b79242cb5f77782.png)

## 设置 Stripe [服务器端] [客户端]

首先，您需要有 Stripe 账户。[立即注册](https://dashboard.stripe.com/register)。

[Stripe Android SDK](https://github.com/stripe/stripe-android) 是开源的，且[有完整的文档](https://stripe.dev/stripe-android/)。

安装 SDK 时，将 `stripe-android` 添加到您的 [app/build.gradle](https://developer.android.com/studio/build/dependencies) 文件的 `dependencies` 块中：

#### Kotlin

```kotlin
plugins {
    id("com.android.application")
}

android { ... }

dependencies {
  // ...

  // Stripe Android SDK
  implementation("com.stripe:stripe-android:23.7.0")
  // Include the financial connections SDK to support US bank account as a payment method
  implementation("com.stripe:financial-connections:23.7.0")
}
```

> 有关最新 SDK 发布及过往版本的详细信息，请查看 GitHub 上的[发布](https://github.com/stripe/stripe-android/releases)页面。要想在新版本发布时接收通知，请[查看仓库的发布情况](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository)。

用您的 Stripe [公钥](https://dashboard.stripe.com/apikeys)配置 SDK，以便它可以向 Stripe API 发送请求，例如在您的 `Application` 子类中：

#### Kotlin

```kotlin
import com.stripe.android.PaymentConfiguration

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        PaymentConfiguration.init(
            applicationContext,
            "<<YOUR_PUBLISHABLE_KEY>>"
        )
    }
}
```

> 测试时使用您的[测试密钥](https://docs.stripe.com/keys.md#obtain-api-keys)，发布应用时使用[真实模式](https://docs.stripe.com/keys.md#test-live-modes)密钥。

## 设置地址自动完成建议

Address Element 使用 [Google Places SDK](https://developers.google.com/maps/documentation/places/android-sdk/overview) 来获取地址自动完成建议。要启用自动完成建议，您需要在应用的 `build.gradle` 中包含 Google Places SDK 依赖项。

#### Groovy

```groovy
dependencies {
    implementation 'com.google.android.libraries.places:places:2.6.0'
}
```

地址自动完成建议需要 Google Places API 密钥。请按照 [Google Places SDK 设置指南](https://developers.google.com/maps/documentation/places/android-sdk/cloud-setup)生成您的 API 密钥。

## 配置 Address Element

可以使用显示默认值、设置允许的国家/地区、自定义外观等详细信息来配置 Address Element。有关配置选项的完整列表，请参阅 [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(
  additionalFields: AddressLauncher.AdditionalFieldsConfiguration(
    phone: AdditionalFieldsConfiguration.FieldConfiguration.Required
  ),
  allowedCountries: setOf("US", "CA", "GB"),
  title: "Shipping Address",
  googlePlacesApiKey = "(optional) YOUR KEY HERE"
)
```

## 检索地址详情

通过在 `Activity` 或 `Fragment` 的 `onCreate` 生命周期方法中创建 `AddressLauncher` 实例，并创建实现 `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
        }
    }
}
```

`AddressLauncherResult` 可以是 `Succeeded` 或 `Canceled`。请参阅更多[实现细节](https://github.com/stripe/stripe-android/blob/master/paymentsheet/src/main/java/com/stripe/android/paymentsheet/addresselement/AddressLauncherResult.kt)。

> Stripe 要求您在 `onCreate` 生命周期事件期间（而不是之后）实例化 `AddressLauncher`。否则，回调无法正确注册，您的应用将崩溃。

## 显示 Address Element

使用地址启动器和先前步骤中的配置来展示 Address Element。

```kotlin
addressLauncher.present(
   publishableKey = publishableKey,
   configuration = addressConfiguration
)
```

## Optional: 在 Payment Element 中预填充收货地址

如果使用移动端 Payment Element，请将[PaymentSheet.Configuration.shippingDetails](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet/-payment-sheet/-configuration/index.html) 设置为地址元素收集的地址。当 `shippingDetails` 被填入时，用户的账单地址会被预填，他们会看到一个**账单地址与收货地址相同**的复选框。当确认 PaymentIntent 时，已填充 `shippingDetails` 的已确认 PaymentIntents 也会填充 [shipping](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-shipping) intent 属性

```kotlin
val configuration = PaymentSheet.Configuration.Builder("Example, Inc.")
  // ...
  .shippingDetails(shippingDetails)
  .build()
```

## Optional: 自定义外观

现在，您已将 Address Element 添加到您的应用程序中，您可以自定义其外观，以匹配应用其余部分的设计。您可以使用 [Appearance API](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=android) 通过 [AddressLauncher.Configuration.appearance](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet.addresselement/-address-launcher/-configuration/index.html) 来配置外观。

## Optional: 设置默认账单详情

要为支付表单中收集的账单详情设置默认值，请配置 `defaultBillingDetails` 属性。`paymentSheet` 会用您提供的值预先填充其字段。

#### 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: 自定义账单地址信息的收集

### 配置账单详情的收集

使用 `BillingDetailsCollectionConfiguration` 指定您希望如何在 PaymentSheet 中收集账单详情。

可以收集客户的姓名、邮件地址、电话号码和地址。

如果希望将默认账单详情关联到 PaymentMethod 对象（即使 UI 中未收集这些字段），请将 `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` 设置为 `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()
```

> 请咨询律师，了解与收集信息有关的法律。仅在需要收集号码来完成交易时，才收集手机号码。


# React Native

> This is a React Native for when payment-ui is mobile and platform is react-native. View the full page at https://docs.stripe.com/payments/mobile/collect-addresses?payment-ui=mobile&platform=react-native.

要收集完整的地址以进行计费或送货，请使用 [Address Element](https://docs.stripe.com/payments/mobile/address-element.md)。

还可以使用 Address Element 执行以下作：

- 收集客户[电话号码](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet.addresselement/-address-launcher/-additional-fields-configuration/index.html)
- 启用[自动完成功能](https://stripe.dev/stripe-android/paymentsheet/com.stripe.android.paymentsheet.addresselement/-address-launcher/-configuration/index.html)
- 通过传入收货地址在 Payment Element 中预填充账单信息

Stripe 将收集的地址信息和支付方式合在一起来创建 *PaymentIntent* (API object that represents your intent to collect payment from a customer, tracking charge attempts and payment state changes throughout the process)。
![用户选择“添加收货地址”选项的结账流程示例。然后，他们被带到一个新的界面，将他们的收货地址添加到一个表单中（他们会在键入地址时看到自动完成建议）。](https://b.stripecdn.com/docs-statics-srv/assets/android-overview.6061212dc737aa700b79242cb5f77782.png)

## 设置 Stripe [服务器端] [客户端]

首先，您需要有 Stripe 账户。[立即注册](https://dashboard.stripe.com/register)。

[React Native SDK](https://github.com/stripe/stripe-react-native) 是开源的并且配备了完整的文档。在内部，它使用原生 [iOS](https://github.com/stripe/stripe-ios) 和 [Android](https://github.com/stripe/stripe-android) SDK。要安装 Stripe 的 React Native SDK，请在项目的目录中运行以下命令之一（具体取决于您使用的软件包管理器）：

#### yarn

```bash
yarn add @stripe/stripe-react-native
```

#### npm

```bash
npm install @stripe/stripe-react-native
```

然后，安装一些其他必要的依赖项：

- 对于 iOS，请转到 **ios** 目录并运行 `pod install` 以确保同时安装了所需的本地依赖项。
- 对于 Android，您无需安装更多依赖项。

### Stripe 初始化

要在您的 React Native 应用中初始化 Stripe，使用 `StripeProvider` 组件包裹您的支付界面，或者使用 `initStripe` 初始化方法。只需要 `publishableKey` 中的 API [公钥](https://docs.stripe.com/keys.md#obtain-api-keys)。下例显示的是用 `StripeProvider` 组件初始化 Stripe 的方式。

```javascript
import { StripeProvider } from '@stripe/stripe-react-native';

function App() {
  return (
    <StripeProvider
      publishableKey="<<YOUR_PUBLISHABLE_KEY>>"
    >
      // Your app code here
    </StripeProvider>
  );
}
```

> 测试与开发时使用 API [测试模式](https://docs.stripe.com/keys.md#obtain-api-keys)，发布时使用[真实模式](https://docs.stripe.com/keys.md#test-live-modes)密钥。

## 设置地址自动完成建议

在 iOS 上，自动完成功能默认启用，但要在 Android 上启用自动完成建议，您需要在应用的 `build.gradle` 中包含 [Google Places SDK 依赖项](https://developers.google.com/maps/documentation/places/android-sdk/overview)：

#### Groovy

```groovy
dependencies {
    implementation 'com.google.android.libraries.places:places:2.6.0'
}
```

地址自动完成建议需要 Google Places API 密钥。请按照 [Google Places SDK 设置指南](https://developers.google.com/maps/documentation/places/android-sdk/cloud-setup)生成您的 API 密钥。

## 配置 Address Element

您可以对 Address Element 进行配置，例如显示默认值、设置允许的国家/地区、定制外观等详细设置。有关更多信息，请参阅[可用选项列表](https://github.com/stripe/stripe-react-native/blob/master/src/components/AddressSheet.tsx#L19-L51)。

```jsx
<AddressSheet
  appearance={{
    colors: {
      primary: '#F8F8F2',
      background: '#272822'
    }
  }}
  defaultValues={{
    phone: '111-222-3333',
    address: {
      country: 'United States',
      city: 'San Francisco',
    },
  }}
  additionalFields={{
    phoneNumber: 'required',
  }}
  allowedCountries={['US', 'CA', 'GB']}
  primaryButtonTitle={'Use this address'}
  sheetTitle={'Shipping Address'}
  googlePlacesApiKey={'(optional) YOUR KEY HERE'}
/>
```

## 显示 Address Element 并检索详细信息

通过将 `visible` 属性设置为 `true` 并为 `onSubmit` 和 `onError` 属性添加回调方法来检索地址详细信息：

```jsx
<AddressSheet
  visible={true}
  onSubmit={async (addressDetails) => {
    // Make sure to set `visible` back to false to dismiss the address element.
    setAddressSheetVisible(false);

    // Handle result and update your UI
  }}
  onError={(error) => {
    if (error.code === AddressSheetError.Failed) {
      Alert.alert('There was an error.', 'Check the logs for details.');
      console.log(err?.localizedMessage);
    }
   // Make sure to set `visible` back to false to dismiss the address element.
    setAddressSheetVisible(false);
  }}
/>
```

## Optional: 在 Payment Element 中预填充收货地址

如果使用移动端 Payment Element，请将[defaultShippingDetails](https://github.com/stripe/stripe-react-native/blob/address-element-private-beta/src/types/PaymentSheet.ts#L17) 设置为地址元素收集的地址。当`defaultShippingDetails` 填入时，用户的账单地址会被预填，他们会看到一个**账单地址与收货地址相同**的复选框。当确认 PaymentIntent 时，已填充 `defaultShippingDetails` 的已确认 PaymentIntents 也会填充 [shipping](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-shipping) intent 属性。

```jsx
const { error } = await initPaymentSheet({
  ...
  defaultShippingDetails: addressDetails,
});
```

## Optional: 自定义外观

现在，您已将 Address Element 添加到您的应用程序中，您可以自定义其外观，以匹配应用程序其余部分的设计。您可以使用 [Appearance API](https://docs.stripe.com/elements/appearance-api/mobile.md?platform=react-native)，通过 `<AddressSheet/>` 组件上的 `appearance` 属性来配置外观。

## Optional: 设置默认账单详情

要为 PaymentSheet 中收集的账单详情设置默认值，请配置 `defaultBillingDetails` 属性。`PaymentSheet` 会用您提供的值预先填充其字段。

```javascript
await initPaymentSheet({
  // ...
  defaultBillingDetails: {
      email: 'foo@bar.com',
      address: {
        country: 'US',
      },
  },
});
```

## Optional: 自定义账单地址信息的收集

用 `billingDetailsCollectionConfiguration` 指定您希望如何在 PaymentSheet 中收集账单详情。

可以收集客户的姓名、邮件地址、电话号码和地址。

如果您不打算收集支付方式需要的值，则必须进行以下操作：

1. 将 `PaymentSheet` 未收集的值附到 `defaultBillingDetails` 属性。
1. 将 `billingDetailsCollectionConfiguration.attachDefaultsToPaymentMethod` 设置为 `true`。

```javascript
await initPaymentSheet({
  // ...
  defaultBillingDetails: {
    email: 'foo@bar.com',
  },
  billingDetailsCollectionConfiguration: {
    name: PaymentSheet.CollectionMode.ALWAYS,
    email: PaymentSheet.CollectionMode.NEVER,
    address: PaymentSheet.AddressCollectionMode.FULL,
    attachDefaultsToPaymentMethod: true
  },
});
```

> 请咨询律师，了解与收集信息有关的法律。仅在需要收集号码来完成交易时，才收集手机号码。