Botsi iOS SDK Documentation

The Botsi SDK enables seamless in-app purchases and paywall management in iOS applications. This documentation covers the public API methods available for integration.

Table of Contents

• Installation
• Initialization
• Profile Management
• Product Management
• Purchase Operations
• Paywall Management

Installation

To integrate the BotsiSDK into your project using Swift Package Manager (SPM), follow these steps:

1. Open Your Project in Xcode
   Launch your iOS project in Xcode.

2. Add the Package Dependency
   From the menu, navigate to File > Swift Packages > Add Package Dependency....

3. Enter the Repository URL
   When prompted, enter the repository URL below:

https://github.com/BotsiTeam/BotsiSDK-iOS

4. Specify the Version
   Under the version rule options, select Version and specify the SDK version:

Latest version is: 1.0.1

5. Finalize Installation
   Xcode will download and integrate the SDK into your project. Once added, you can start using the SDK immediately.

6. Import the SDK in Your Code
   In your source files, add the following import statement:

import Botsi

CocoaPods

To integrate the BotsiSDK into your project using CocoaPods, follow these steps:

1. Add the SDK to your Podfile and add the following line: pod 'BotsiSDK', '~> 1.0.1'

2. Install the PodRun the following command to install the SDK: pod install

3. Open the generated .xcworkspace file in Xcode instead of the .xcodeproj.

Initialization

activate(_ key:)

static func activate(_ key: String) async throws

Activates and initializes the Botsi SDK with your public key.

Example:

do {
    try await Botsi.activate("your_api_key")
    // SDK is now initialized and ready for use
} catch let error as BotsiError {
    print("Failed to initialize Botsi SDK: \(error.localizedDescription)")
} catch {
    print("Unknown error")
}

isInitialized

static var isInitialized: Bool { get async }

Checks if the Botsi SDK has been properly initialized.

Returns:

• Bool: true if the SDK has been initialized, false otherwise.

Example:

let initialized = await Botsi.isInitialized
if initialized {
    // SDK is ready to use
} else {
    // SDK needs to be initialized
}

identify(_ userId: String)

static func identify(_ userId: String) async throws

Links the SDK session to a specific user in your own system. If you didn’t provide a user ID when initializing the SDK, you can call .identify() at any point—most often right after the user signs up or logs in, moving from an anonymous session to an authenticated one.

Parameter userId: The unique identifier for the user in your system.

Example:

do {
    let currentUserId = "user_12345"
    try await Botsi.identify(currentUserId)
    // The SDK session is now linked to the authenticated user
} catch let error as BotsiError {
    print("Failed to identify user: \(error.localizedDescription)")
} catch {
    print("Unexpected error during user identification: \(error)")
}

logout()

static func logout() async throws

Ends the current user session and reverts the SDK to an anonymous state.

Calling .logout() removes any stored user identifier and clears session-specific data, so subsequent calls behave as if no user is signed in. Use this when the user signs out or you need to reset personalization.

• Note: After logging out, you can call .identify() again to link a new or returning user.

Example:

do {
    try await Botsi.logout()
    // The SDK session is reverted to an anonymous state
} catch let error as BotsiError {
    print("Failed to logout user: \(error.localizedDescription)")
} catch {
    print("Unexpected error during user logout: \(error)")
}

Profile Management

getProfile()

static func getProfile() async throws -> BotsiProfile

Retrieves the current user's profile information.

Returns:

• BotsiProfile: The user's profile with information about their purchases and entitlements.

Throws:

• BotsiError.userProfileNotFound: If no profile has been created for the current user.

Example:

do {
    let profile = try await Botsi.getProfile()
    print("User profile ID: \(profile.profileId)")
    // Access other profile properties
} catch let error as BotsiError {
    print("Failed to get user profile: \(error)")
}

Product Management

fetchProductIDs()

static func fetchProductIDs() async throws -> [String]

Retrieves the list of product IDs available for the application.

Returns:

• [String]: Array of product identifiers that can be used for purchases.

Example:

do {
    let productIDs = try await Botsi.fetchProductIDs()
    print("Available product IDs: \(productIDs)")
} catch let error as BotsiError {
    print("Failed to fetch product IDs: \(error)")
}

Purchase Operations

makePurchase(_:)

static func makePurchase(_ productId: String) async throws -> BotsiProfile

Initiates a purchase for the specified product ID.

Parameters:

• productId: The identifier of the product to purchase.

Returns:

• BotsiProfile: Updated user profile after the purchase is complete.

Throws:

• BotsiError.transactionFailed: If the purchase transaction fails.
• BotsiError.customError: With details if there are issues with StoreKit handlers.

Example:

do {
    let updatedProfile = try await Botsi.makePurchase("product_id")
    // Handle successful purchase
    print("Purchase successful! Updated profile: \(updatedProfile.profileId)")
} catch let error as BotsiError {
    print("Purchase failed: \(error)")
}

restorePurchases()

static func restorePurchases() async throws -> BotsiProfile

Restores previously purchased products for the current user.

Returns:

• BotsiProfile: Updated user profile with restored purchases.

Throws:

• BotsiError.restoreFailed: If the restore operation fails.

Example:

do {
    let restoredProfile = try await Botsi.restorePurchases()
    print("Purchases restored successfully!")
    // Check restored entitlements
} catch let error as BotsiError {
    print("Failed to restore purchases: \(error)")
}

Paywall Management

getPaywall(from:)

static func getPaywall(from placementId: String) async throws -> BotsiPaywall

Retrieves a paywall configuration for the specified placement ID.

Parameters:

• placementId: The identifier of the paywall placement.

Returns:

• BotsiPaywall: The paywall configuration with UI elements and product references.

Throws:

• BotsiError.userProfileNotFound: If no user profile exists.
• BotsiError.sdkActivationKeyNotValid: If user entered wrong public key.
• BotsiError.customError: With details if there are issues with fetching profile.

Example:

do {
    let paywall = try await Botsi.getPaywall(from: "paywall_name")
    // Configure your UI with the paywall information
    print("Paywall retrieved: \(paywall)")
} catch let error as BotsiError {
    print("Failed to get paywall: \(error)")
}

getPaywallProducts(from:)

static func getPaywallProducts(from paywall: BotsiPaywall) async throws -> [BotsiProduct]

Retrieves detailed product information for all products in a paywall.

Parameters:

• paywall: A BotsiPaywall object obtained from getPaywall(from:).

Returns:

• [BotsiProduct]: Array of product details including pricing, description, and other StoreKit information.

Example:

do {
    let paywall = try await Botsi.getPaywall(from: "paywall_name")
    let products = try await Botsi.getPaywallProducts(from: paywall)
    
    // Display products to the user
    for product in products {
        print("Product: \(product.title)")
        print("Price: \(product.price)")
        // Configure purchase buttons with product information
    }
} catch let error as BotsiError {
    print("Failed to get paywall products: \(error)")
}

logPaywallShown()

    static func logPaywallShown(for paywall: BotsiPaywall) async throws

Sends an event to collect analytics. Should be called together with getPaywall(from:)

Example:

do {
    let paywall = try await Botsi.getPaywall(from: "paywall_name")
    try await Botsi.logPaywallShown(for: paywall)
} catch let error as BotsiError {
    print("Failed to get paywall or send event: \(error)")
}

Error Handling

The SDK uses BotsiError for error reporting. Common errors include:

• BotsiError.userProfileNotFound: No profile exists for the current user
• BotsiError.transactionFailed: Purchase transaction failed
• BotsiError.restoreFailed: Restore purchases operation failed
• BotsiError.customError: Custom errors with detailed information
• BotsiError.paywallFetchingFailed: Failed to fetch paywall information
• BotsiError.sdkActivationKeyNotValid: Incorrect public key provided

Properly handle these errors in your application to provide appropriate feedback to users.