Chargebee 1.0.28

Chargebee 1.0.28

×

由 HP Team Chargebee 维护。

Chargebee 1.0.28

  • 作者：
  • cb-imay

Chargebee iOS

这是 Chargebee iOS 的官方软件开发工具包（SDK）。此 SDK 可以使您在 iOS 应用中构建令人印象深刻的订阅体验变得高效、舒适。

安装后，与 Chargebee 网站进行初始化和身份验证，此 SDK 将支持以下过程。

  • 同步 In-App 订阅与 Chargebee：集成 Apple Store Connect 处理 In-App 购买订阅，并在您的 Chargebee 账户中跟踪它们，以获得 Web 和 Apple App Store 上订阅的单一点真相。如果您正在销售数字商品或服务，或者必须根据其应用审查标准 使用 Apple 的 In-App 购买，请使用此功能。为了 SDK 功能能够正常工作，确保在 Chargebee 中配置了以下 先决条件 。若要导入在 Apple App Store 中配置的产品和现有订阅，请阅读更多信息。

  • 信用卡信息加密：在呈现您自己的用户界面时加密信用卡信息。如果您正在销售实体商品或线下服务或不需要根据其应用审查标准 使用 Apple 的 In-App 购买，请使用此功能。

  • 注意：此 SDK 不支持使用 Objective C 开发的应用程序。如果您的应用程序使用 Objective C 开发，我们可以指导您将 Objective C 与我们的 SDK 代码集成。请联系[email protected]

需求

在安装 Chargebee 的 iOS SDK 之前，必须设置以下需求

  • iOS 12+

  • Swift 5+

安装

请从以下选项中选择安装 Chargeee iOS SDK。

GitHub

将以下代码片段添加到 Podfile 中，以直接从 GitHub 安装。

pod 'Chargebee', :git => 'https://github.com/chargebee/chargebee-ios', :tag => '1.0.25'

CocoaPods

将以下行添加到 Podfile 中，以使用 CocoaPods 安装。

pod 'Chargebee'

Swift Package Manager

按照步骤使用 Swift Package Manager 安装 SDK。

示例项目

这是一个可选步骤，可以帮助您通过此示例项目验证SDK实现。您可以通过GitHub下载或克隆此示例项目。

要运行示例项目，请按照以下步骤操作。

配置SDK

有两种配置类型。

  • 内购配置

  • 基于令牌的信用卡配置

内购配置

要为完成和管理内购配置Chargebee iOS SDK，请按照以下步骤操作。

  • 集成 App Store Connect 与您的 Chargebee网站。

  • 在Web应用的同步概述页面，点击查看密钥，并使用生成的应用ID的值作为SDK密钥。

  • 在Chargebee网站上，导航到配置Chargebee > API密钥以创建一个新的可发布API密钥或使用现有的可发布API密钥。 注意：在创建可发布API密钥时，必须允许对计划/商品进行只读访问，否则此密钥在以下步骤中将不起作用。更多信息请参阅这里。

  • 通过在应用启动时将以下代码片段包含在您的应用代理中进行初始化，使用您的Chargebee网站、可发布API密钥和SDK密钥初始化SDK。

import Chargebee

Chargebee.configure(site: "your-site",
                    apiKey: "publishable_api_key",
                    sdkKey: "ResourceID/SDK Key")
}

使用令牌化配置信用卡

要仅配置SDK对信用卡详细信息进行令牌化，请遵循以下步骤。

  • 使用您的Chargebee网站和可发布/完整访问密钥初始化SDK。

  • 通过将以下代码片段包含在您的应用代理中，在应用启动时初始化SDK。

import Chargebee

Chargebee.configure(site: "your-site", apiKey: "publishable_api_key")

SDK集成过程

本节描述了SDK集成过程。

  • 集成应用内购买

  • 集成信用卡令牌化

集成应用内购买

以下部分描述了如何使用SDK集成应用内购买信息。有关应用内购买的详细信息，请参阅更多。

从Chargebee获取所有IAP产品ID

您在App Store Connect账户中配置的每个应用内购买订阅产品都可以在Chargebee中配置为计划。首先，从您的Chargebee账户检索Apple IAP产品ID。

CBPurchase.shared.retrieveProductIdentifers(queryParams :["String": "String"], completion:  { result in
switch result {
    case let .success(products):
        print("array of Products Id's \(products)")
    case let .failure(error):
        // Handle error here
}
})

例如，可以传递查询参数，如 "limit": "100"。

上述功能会自动确定你的Chargebee产品目录版本，并调用相关API来检索与苹果IAP产品和它们对应的苹果IAP产品ID相对应的Chargebee计划。

获取IAP产品

你可以使用以下函数将IAP产品ID转换为苹果IAP产品对象。

CBPurchase.shared.retrieveProducts(withProductID : ["Product ID from Apple"],completion: { result in
    switch result {
    case let .success(products):
        print("array of Products \(products)")
    case let .failure(error):
        // Handle error here
}
}

然后你可以向用户提供上述任何产品以便他们购买。

购买或订阅产品

当用户选择要购买的产品时，请将CBProduct和CBCustomer对象传递到以下函数。

CBCustomer - 可选对象。虽然这是一个可选对象，但我们在用户在您的App中订阅之前，建议添加必要客户信息，如customerID、firstName、lastName和email，如果可用的。这确保了你在数据库中的客户信息与Chargebee中的客户信息相匹配。如果客户详细资料中没有传递customerID，则customerID的值将与Chargebee中创建的SubscriptionId相同。

注意: 下面代码片段中的customer参数是包含想要订阅或购买产品客户详细信息的CBCustomer类的实例。

    let product = CBProduct(product: SKProduct())
    let customer = CBCustomer(customerID: "",firstName:"",lastName: "",email: "")
    CBPurchase.shared.purchaseProduct(product: product,customer: customer) { result in
    switch result {
        case .success(let result):
            print(result.status)
            print(result.subscriptionId) // this will print the subscription ID 
            print(result.planId) // this will print the Plan ID 
        case .failure(let error):
            // Handle error here
    }
}

上述功能将处理App Store Connect中的购买，并将IAP收据发送到你的Chargebee账户以进行服务器端收据验证。使用上述函数返回的订阅ID，在Chargebee上检查订阅状态并确认访问权限 - 授予或拒绝。

该函数还返回与订阅关联的计划ID。你可以在Chargebee中为苹果App Store计划关联JSON元数据，并通过将计划ID传递到SDK函数 - retrievePlan(PC 1.0) 或 retrieveItem(PC 2.0) 中检索相同的计划。

一次性购买

purchaseNonSubscriptionProduct函数处理一次购买操作，针对App Store Connect进行操作并发送IAP收据到您的Chargebee账户进行服务器端收据验证。验证通过后在Chargebee中创建对应的一次性购买账单。一次性购买有三种类型：consumable、non_consumable和non_renewing_subscription。

let product = CBProduct(product: SKProduct())
    let customer = CBCustomer(customerID: "",firstName:"",lastName: "",email: "")
    let typeOfProduct: productType = .non_consumable
    CBPurchase.shared.purchaseNonSubscriptionProduct(product: withproduct,customer: customer,productType: typeOfProduct) { result in
      switch result {
      case .success(let success):
        print(result.customerID)
        print(result.chargeID ?? "")
        print(result.invoiceID ?? "")
      case .failure(let failure):
        //Hanler error here
      }
    }

给定的代码在CBPurchase类中定义了一个基于闭包的函数purchaseNonSubscriptionProduct，该函数接受三个输入参数：

  • product：一个CBProduct类的实例，用代表要从苹果App Store购买的产品的SKProduct实例初始化。
  • customer：一个CBCustomer类的实例，用客户的详细信息初始化，如customerID、firstName、lastName和email。
  • productType：一个指示要购买的产品类型的枚举实例，可以是productType类型的consumable、non_consumable或non_renewing_subscription。

该函数以异步方式调用，并返回一个包含success或failure情况的结果对象，可以在闭包中处理。

  • 如果购买成功，闭包将以success情况调用，该情况包括与购买相关的customerID、chargeID和invoiceID。
  • 如果在购买过程中出现错误，闭包将以failure情况调用，该情况包括一个错误对象，可以用来处理错误。

恢复购买

restorePurchases()函数有助于恢复您的应用程序用户之前的购买，而无需再次支付。有时，您的应用程序用户可能会在切换到新设备或重新安装您的应用程序后希望恢复之前的购买。您可以使用restorePurchases()函数让您的应用程序用户轻松恢复之前的购买。

要获取您的应用程序用户的inactive购买以及active购买，可以将restorePurchases()函数的includeInActiveProducts参数设置为true。如果您只想恢复活跃的订阅，请将参数设置为false。以下是如何使用设置includeInActiveProducts参数为true的restorePurchases()函数的示例。

CBPurchase.shared.restorePurchases(includeInActiveProducts: true) { result in
      switch result {
      case .success(let response):
        for subscription in response {
          if subscription.storeStatus.rawValue == StoreStatus.Active.rawValue{
            print("Successfully restored purchases")
          }
        }
      case .failure(let error):
        // Handle error here
        print("Error:",error)
      }
    }
返回订阅对象

restorePurchases() 函数返回一个订阅对象数组，每个对象包含三个属性 subscription_id、plan_id 和 store_status。可以用于验证订阅状态的 store_status 值。

错误处理

在刷新和验证过程或寻找要恢复项目的相关订阅时出现任何失败，iOS SDK 将返回以下表格所述的错误。

错误代码

以下是可能出现的错误代码及其描述

错误代码 描述
RestoreError.noReceipt 当用户尝试恢复购买，但与购买相关的收据不存在时，此错误发生。
RestoreError.refreshReceiptFailed 尝试刷新购买的收据失败时，此错误发生。
RestoreError.restoreFailed 尝试恢复购买失败时，此错误发生（除了缺失或无效的收据之外的其他原因）。
RestoreError.invalidReceiptURL 在恢复过程中提供的收据包的 URL 无效或无法访问时，此错误发生。
RestoreError.invalidReceiptData 当收据中包含的数据无效或无法解析时，此错误发生。
RestoreError.noProductsToRestore 没有可恢复的产品时，此错误发生。
RestoreError.serviceError 在恢复过程中，当 Chargebee 服务出现问题时，此错误发生。

注意：这些错误代码在示例应用中实现。 了解更多。

苹果 App Store 购买与 Chargebee 通过收据验证的同步

收据验证对于确保用户在 Chargebee 中同步完成的购买至关重要。在罕见情况下，当在 Apple App Store 完成购买但网络连接中断时，购买详情可能不会在 Chargebee 中更新。在这种情况下，您可以通过以下步骤使用重试机制：

  • 如示例项目所示，添加网络观察器。
  • 购买开始时在缓存中保存产品标识符，购买成功后清除缓存。
  • 当在 Apple App Store 完成购买后，网络连接中断但未与 Chargebee 同步时，在网络连接恢复后从缓存中检索产品 ID，并通过传递 CBProduct 和 CBCustomer(Optional) 作为输入来启动 validateReceipt()/validateReceiptForNonSubscriptions()。这将验证购买收据并在 Chargebee 中同步购买作为订阅或一次性购买。对于订阅，使用函数 validateReceipt()；对于一次性购买，使用函数 validateReceiptForNonSubscriptions()。

使用可用的重试机制函数。

订阅函数

CBPurchase.shared.validateReceipt(product,customer: nil) { result in
      switch result {
      case .success(let result):
        print(result.status )
        // Clear persisted product details once the validation succeeds.
      case .failure(let error):
        print("error",error.localizedDescription)
        // Retry based on the error
      }
    }

一次性购买函数

CBPurchase.shared.validateReceiptForNonSubscriptions(product,type,customer: nil) { result in
        switch result {
        case .success(let result):
          // Clear persisted product details once the validation succeeds.
        case .failure(let error):
       // Retry based on the error
        }
      }

获取现有订阅者的订阅状态

以下用于检查已购买产品的购买者的订阅状态的函数。

使用查询参数获取现有订阅者的订阅状态

使用查询参数（订阅 ID、客户 ID 或状态）检查在 Chargebee 上的订阅状态并确认访问权限 - 被授权或被拒绝。

Chargebee.shared.retrieveSubscriptions(queryParams :["String" : "String"]") { result in
    switch result {
    case let .success(resultarray):
        print("Status \(resultarray.first.subscription.status)")
    case let .error(error):
        // Handle error here
    }
}

例如，查询参数可以传递为 "customer_id" : "id"，"subscription_id": "id" 或 "status": "active"。

使用订阅ID获取现有订阅者的订阅状态

使用订阅ID在Chargebee上检查订阅状态并确认访问权限 - 授予或拒绝。

Chargebee.shared.retrieveSubscription(forID: "SubscriptionID") { result in
    switch result {
    case let .success(result):
        print("Status \(result.status)")
    case let .error(error):
        // Handle error here
    }
}

上述函数返回与订阅相关联的计划ID。您可以在Chargebee中的Apple App Store计划中关联JSON元数据，并通过将计划ID传递给SDK函数来检索它 - retrievePlan(PC 1.0) 或 retrieveItem(PC 2.0)。

获取订阅的权限列表

使用订阅ID来检索与订阅相关联的权限列表。

Chargebee.shared.retrieveEntitlements(forID: "SubscriptionID") { result in
    switch result {
    case let .success(result):
        print("Status \(result.status)")
    case let .error(error):
        // Handle error here
    }
}

注意：权限功能仅在您的Chargebee站点位于产品目录2.0时可用。

集成信用卡令牌化

以下部分描述了如何使用SDK来令牌化信用卡信息。

产品目录 2.0

如果您的Chargebee网站配置了PC 2.0，请使用以下功能检索购买的上市产品或产品列表。

获取所有商品

使用以下函数检索商品列表。

  CBItem.retrieveAllItems(queryParams :["String" : "String"], completion:  { result in
                DispatchQueue.main.async {
                    switch result {
                    case let .success(itemLst):
                        self.items =  itemLst.list
                        debugPrint("items: \(self.items)")
                        self.performSegue(withIdentifier: "itemList", sender: self)
                    case let .error(error):
                        debugPrint("Error: \(error.localizedDescription)")
                    }
                }
    })

例如，可以将查询参数传递为 "sort_by[desc]" : "name" 或 "limit": "100"。

获取商品详情

使用以下函数检索特定商品的详细信息。使用从前一个函数 - 获取所有商品收到的 Item ID。

CBItem.retrieveItem("Item ID"){ (itemResult) in
            switch itemResult {
            case .success(let item):
                print(item)
                self.itemName.text = item.name
                self.itemStatus.text = item.status

            case .error(let error):
                print("Error\(error)")
                self.error.text = error.localizedDescription
            }
        }

产品目录 1.0

如果您的Chargebee网站配置为PC 1.0，请使用相关函数来检索购买的产品或产品列表。

获取所有计划

使用以下函数检索计划列表。

CBPlan.retrieveAllPlans(queryParams: ["String":"String" ]) { (result) in
    switch result {
    case .success(let plan):
        print("Plan Array: \(plan)")
        // Use plan details here
    case .error(let error):
        // Handle error here
    }
}

例如，可以将查询参数传递为 "sort_by[desc]" : "name" 或 "limit": "100"。

获取计划详情

使用以下函数传递计划ID检索特定计划详情。

CBPlan.retrieve("planId") { (planResult) in
    switch planResult {
    case .success(let plan):
        print("Plan Name: \(plan.name)")
        // Use plan details here
    case .error(let error):
        // Handle error here
    }
}
获取插件详情

使用以下函数传递插件ID检索特定插件详情。

CBAddon.retrieve("addonId") { (addonResult) in
    switch addonResult {
    case .success(let addon):
        print("Addon Name: \(addon.name)")
        // Use addon details here
    case .error(let error):
        // Handle error here
    }
}

获取支付令牌

用户选择要购买的产品后，您收集信用卡信息，使用以下函数将信用卡详情与Stripe令牌化。您需要将Stripe账户连接到您的Chargebee网站。

let card = CBCard(
        cardNumber: "4321567890123456",
        expiryMonth: "12",
        expiryYear: "29",
        cvc: "123")

let paymentDetail = CBPaymentDetail(type: CBPaymentType.Card, currencyCode: "USD", card: card)

Chargebee.shared.createTempToken(paymentDetail: paymentDetail) { tokenResult in
    switch tokenResult {
    case .success(let token):
        print("Chargebee Token \(token)")
        // Use token here
    case .error(let error):
        // Handle error here
    }
}

使用Chargebee令牌

客户卡片数据被处理和存储，且有一个Chargebee令牌引用返回给您后，使用该令牌在后续API调用中处理事务。

以下是一些接受Chargebee令牌处理订阅的端点。

有关后续集成步骤，请参阅Chargebee API 文档

升级或降级订阅

当用户从较低价格的计划更改为较高价格的计划时，被认为是一次升级。相反，当用户从较高价格计划切换到较低价格计划时，被认为是一次降级。

在Apple App Store的情况下，您可以在App Store Connect中通过“编辑订阅订单”中的拖放选项来安排订阅。了解更多信息。

在您的应用中调用升级或降级订阅流程

showManageSubscriptionsSettings()函数设计用于使用Chargebee的iOS SDK在您的应用中调用升级/降级流程。调用Chargebee.shared.showManageSubscriptionsSettings()，将打开App Store应用订阅设置页面。

注意：升级和降级通过Chargebee中的Apple App Store服务器通知处理。

许可证

Chargebee根据MIT许可证提供。有关更多信息，请参阅LICENSE文件。