PayPal Android SDK迁移指南：从Mobile Checkout到Native Payments

前言

随着PayPal支付生态的演进，原有的Mobile Checkout SDK即将停止维护，取而代之的是全新的PayPal Android SDK（Native Payments）。本文将为开发者提供详细的迁移指南，帮助您顺利完成从旧版SDK到新版SDK的过渡。

迁移前的准备工作

在开始迁移前，请确保您的开发环境满足以下条件：

1. 服务器端集成：必须使用PayPal Orders v2 API进行服务器端集成。如果您仍在使用Payments V1或NVP/SOAP接口，需要先升级到Orders v2。

2. 客户端ID：从PayPal开发者控制台获取有效的客户端ID。

3. 订单创建能力：服务器端需要能够创建订单ID。

4. 订单更新能力：服务器端需要支持PATCH操作来更新订单。注意：只有当订单创建时使用shipping_preference=GET_FROM_FILE参数时才需要此功能。

客户端迁移步骤

1. 添加新版SDK依赖

在应用级的build.gradle文件中添加以下依赖：

dependencies {
    implementation "com.paypal.android:paypal-native-payments:<最新版本>"
    implementation "com.paypal.android:payment-buttons:<最新版本>"
}

2. 配置更新

旧版SDK使用CheckoutConfig进行全局配置，新版SDK改为使用CoreConfig和PayPalNativeCheckoutClient：

// 移除Application类中的CheckoutConfig配置

class MainActivity : AppCompatActivity() {
    private lateinit var paypalClient: PayPalNativeCheckoutClient
    
    fun configurePayPalCheckout() {
        val coreConfig = CoreConfig("您的客户端ID", environment = Environment.SANDBOX)
        
        paypalClient = PayPalNativeCheckoutClient(
            application = application,
            coreConfig = coreConfig,
            returnUrl = "${BuildConfig.APPLICATION_ID}://paypalpay"
        )
    }
}

3. 支付按钮更新

新版SDK使用PayPalButton替代了旧版的PaymentButtonContainer：

<!-- 布局文件中的变更 -->
<com.paypal.android.paymentbuttons.PayPalButton
    android:id="@+id/paypal_button"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"/>

// Activity中的变更
paypalButton = findViewById(R.id.paypal_button) as PayPalButton
paypalButton.setOnClickListener {
    paypalButtonTapped()
}

4. 实现点击监听器

创建支付请求并启动支付流程：

fun paypalButtonTapped() {
    val request = PayPalNativeCheckoutRequest("您的订单ID")
    paypalClient.startCheckout(request)
}

5. 实现支付结果监听器

新版SDK使用PayPalNativeCheckoutListener替代了旧版的多回调接口：

paypalClient.listener = object : PayPalNativeCheckoutListener {
    override fun onPayPalCheckoutStart() {
        // 支付页面即将显示
    }
    
    override fun onPayPalSuccess(result: PayPalNativeCheckoutResult) {
        // 支付成功处理
    }
    
    override fun onPayPalFailure(error: PayPalSDKError) {
        // 支付失败处理
    }
    
    override fun onPayPalCanceled() {
        // 用户取消支付
    }
}

6. 实现物流信息监听器（可选）

只有当订单创建时使用shipping_preference=GET_FROM_FILE参数时才需要实现此监听器：

paypalClient.shippingListener = object : PayPalNativeShippingListener {
    override fun onPayPalNativeShippingAddressChange(
        actions: PayPalNativePaysheetActions,
        shippingAddress: PayPalNativeShippingAddress
    ) {
        // 用户修改了配送地址
        actions.approve() // 必须调用approve或reject
    }
    
    override fun onPayPalNativeShippingMethodChange(
        actions: PayPalNativePaysheetActions,
        shippingMethod: PayPalNativeShippingMethod
    ) {
        // 用户修改了配送方式
        try {
            patchOrder() // 更新订单信息
            actions.approve()
        } catch (e: Exception) {
            actions.reject()
        }
    }
}

7. 移除旧版SDK依赖

最后，从build.gradle文件中移除旧版SDK依赖：

dependencies {
    // 移除以下行
    // implementation "com.paypal.checkout:android-sdk"
}

迁移注意事项

1. 测试环境验证：建议先在Sandbox环境下完成迁移验证，再切换到生产环境。

2. 错误处理：新版SDK的错误处理机制有所变化，请确保充分测试各种异常场景。

3. UI适配：新版支付按钮的样式可能与旧版有所不同，请检查UI适配情况。

4. 性能监控：迁移后建议增加性能监控，确保支付流程的稳定性。

结语

通过以上步骤，您应该能够顺利完成从PayPal Mobile Checkout SDK到新版PayPal Android SDK的迁移。新版SDK提供了更简洁的API设计和更好的性能表现，将为您的应用带来更优质的支付体验。如果在迁移过程中遇到任何问题，建议查阅官方文档获取最新信息。