Cello for iOS

​

Installation

​

SDK size

​

Setup

​

Install Cello

​

Option 1: CocoaPods

target :YourTargetName do
  pod 'CelloSDK'
end

​

Option 2: Swift Package Manager

​

Option 3: Install Cello manually

1. Download Cello for iOS and extract the zip. (👉 Cello iOS zip download)
2. Drag CelloSDK.xcframework into your project. Make sure Copy items if needed is selected and click Finish.
3. In the target settings for your app, set the CelloSDK.xcframework to Embed & Sign in the Frameworks, Libraries, and Embedded Content section of the General tab.

​

Choose an Environment

• prod (Production)
• sandbox (Sandbox)

​

Configuration Steps

• Open your iOS project in Xcode.
• Navigate to the Info.plist file.
• Add a new key-value pair:
  Copy

  Ask AI

  <key>CELLO_ENV</key>
  <string>prod</string>
  

• To switch to sandbox, change the string value to sandbox.
• Save your changes. The next build will use the selected environment.

​

Initialize Cello

import CelloSDK

Cello.initialize(for: "YOUR_PRODUCT_ID", with: token) { result in
   switch result {
   case .success(let configuration):
      print("Initialization successful with config:", configuration)
   case .failure(let error):
      print("Initialization failed with error:", error)
   }
}

​

Customize the Cello Referral Component

​

Choose your launcher

• Default launcher: Use Cello.showFab() to present a pre-styled Floating Action Button (FAB).
  Copy

  Ask AI

  import CelloSDK
  Cello.showFab()
  

• Custom launcher: Use any UI element (button, menu item, gesture) and call Cello.openWidget() when you want to open it.
  Copy

  Ask AI

  import CelloSDK
  
  class YourViewController: UIViewController {
      override func viewDidLoad() {
          super.viewDidLoad()
          let myButton = UIButton(type: .system)
          myButton.setTitle("Open Referral", for: .normal)
          myButton.addTarget(self, action: #selector(didTapMyButton), for: .touchUpInside)
          // Add 'myButton' to your view
      }
  
      @objc func didTapMyButton() {
          Cello.openWidget()
      }
  }
  

​

Advanced: Custom Callbacks

class YourViewController: UIViewController, CelloDelegate {
    func celloWidgetDidOpen() {
        print("Cello widget opened")
    }
    func celloWidgetDidClose() {
        print("Cello widget closed")
    }
    override func viewDidLoad() {
        super.viewDidLoad()
        Cello.delegate = self
    }
}

​

iOS API

​

Cello.initialize()

import CelloSDK

let productUserDetails = CelloSDK.ProductUserDetails(
    firstName: "John",
    lastName: "Doe", 
    fullName: "John Doe",
    email: "john.doe@example.com"
)

Cello.initialize(for: "dev.cello.so", with: token, productUserDetails: productUserDetails) { result in
   switch result {
   case .success(let configuration):
       print("Initialization successful with config:", configuration)
   case .failure(let error):
       print("Initialization failed with error:", error)
   }
}

​

Cello.showFab()

import CelloSDK
Cello.showFab()

​

Cello.hideFab()

import CelloSDK
Cello.hideFab()

​

Cello.openWidget()

import CelloSDK
Cello.openWidget()

​

Cello.hideWidget()

import CelloSDK
Cello.hideWidget()

​

Cello.getActiveUcc()

import CelloSDK
let result = Cello.getActiveUcc()

​

getCampaignConfig()

import CelloSDK
let result = Cello.getCampaignConfig()

​

Returns

​

Cello.changeLanguage()

import CelloSDK
Cello.changeLanguage(to: .de)

​

Cello.shutdown()

import CelloSDK
Cello.shutdown()

​

Error Handling

The operation couldn't be completed. (CelloSDK.APIError error N.)

​

Error Codes Reference

​

Error 0: Invalid URL

• Missing or empty product ID
• Malformed base URL in SDK configuration
• Invalid characters in URL parameters

​

Error 1: Unauthorized

• Expired JWT token
• Invalid token signature
• Token generated for a different product ID
• User permissions revoked
• Initializing for wrong environment

​

Error 2: Request Failed

• -1: Network connectivity error (no internet, timeout)
• 400-499: Client errors (bad request, not found)
• 500-599: Server errors

• No internet connection
• Slow or unstable network
• Server maintenance or downtime
• Firewall or proxy blocking requests

​

Error 3: Invalid Response Type

• Network proxy modifying responses
• Server misconfiguration
• Non-HTTP protocol response

​

Error 4: No Data Received

• Server returning empty response
• Network issue truncating the response
• Incorrect API endpoint or version

​

Error 5: JSON Parsing Error

• Server returned HTML error page instead of JSON
• Malformed or incomplete response
• API version mismatch

​

Error 6: Invalid State

• “Product ID cannot be empty”
• “Token cannot be empty”
• “Product ID not set”
• “Configuration not initialized”

• Empty product ID or token during initialization
• Calling SDK methods before initialization completes

​

Initialization State Errors

• "Error: showFab() called before initialization."
• "Error: hideFab() called before initialization."
• "Error: openWidget() called before initialization."
• "Error: hideWidget() called before initialization."
• "Error: shutdown() called before initialization."
• "Error: getActiveUcc() called before initialization."
• "Error: getCampaignConfig() called before initialization."
• "Error: changeLanguage() called before initialization."

​

Error Handling Best Practices

guard !productId.trimmingCharacters(in: .whitespaces).isEmpty else {
    print("Error: Product ID is required")
    return
}

guard !token.trimmingCharacters(in: .whitespaces).isEmpty else {
    print("Error: Token is required")
    return
}

Cello.initialize(for: productId, with: token) { result in
    // Handle result
}

class CelloManager {
    private var isInitialized = false

    func initialize(productId: String, token: String) {
        Cello.initialize(for: productId, with: token) { [weak self] result in
            if case .success = result {
                self?.isInitialized = true
            }
        }
    }

    func showReferral() {
        guard isInitialized else {
            print("SDK not initialized yet")
            return
        }
        Cello.openWidget()
    }
}