Cello for iOS

The Cello SDK for iOS enables you to add a referral program into your iOS app. With a plug-n-play mobile component, your users can easily share their invite link with their friends and network using mobile sharing options convenient for them, receive rewards and get paid out.

Customizations

You can customize the Referral component in the following ways:

• Launcher – Use the default button or implement a custom launcher to open the Referral component.
• Hero Image – Set a custom image for the sharing screen.
• Copy – Customize the text displayed in the component.
• Brand Color – Apply your brand’s primary color to match your app’s style.
• Notification images - Choose which image is displayed in the new view and new reward notification.

Installation

A basic installation takes around 15 minutes but will take a little longer if you want to customize the way the Cello Referral Component is launched.

Compatibility

Cello for iOS is compatible with iOS 15 and up.

SDK size

The size of Cello for iOS varies depending on your app’s configuration. For most installations, it’s around 3MB in size.

Setup

Install Cello to see and give your users the option to spread the word from your iOS app. The Cello for iOS library supports iOS 15+ and requires Xcode 14 to build.

Install Cello

Option 1: CocoaPods

Using the latest version of Cocoapods, add CelloSDK to your Podfile and run pod install

target :YourTargetName do

  pod 'CelloSDK'

end

Option 2: Swift Package Manager

Add https://github.com/getcello/cello-ios-sp as a Swift Package Repository in Xcode and follow the instructions to add CelloSDK as a Swift Package.

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”. This can be found in the “Frameworks, Libraries, and Embedded Content” section of the “General” tab.

Choose an Environment

In your Cello SDK setup, you have the flexibility to select the environment in which your application will run. This feature is especially useful for different stages of development, such as testing in a development or staging environment before going live in production. The available environments are:

• prod (Production)
• sandbox (Sandbox)

By default, the SDK is set to the prod environment.

Configuration Steps

• Open your iOS project in Xcode.
• Navigate to the Info.plist file.
• Add a new key-value pair:
  • Key: CELLO_ENV
  • Value: Set to your desired environment, such as prod for production.

Here is an example of setting the environment to production:

<key>CELLO_ENV</key>

<string>prod</string>

• To switch environments, simply change the value of CELLO_ENV. For example, to set the environment to sandbox:

<string>sandbox</string>

• Save your changes. The next time you build your project, it will run using the specified environment setting.

Using this setup, the Cello SDK on iOS can adapt to the chosen environment, allowing a smoother and more controlled development and testing process.

Initialize Cello

In this step, you will need your product ID and a token you have generated for the user, similar when implementing the web based Referral component.

Initialize Cello by importing Cello and adding the following to your application delegate:

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

The Cello SDK allows for various levels of customization to better fit into your app's design and flow. One of the main components you might want to customize is the Referral component

Choose your launcher

The SDK provides two ways to launch the Referral component:

Default launcher

If you choose to go with the default launcher, you can call the showFab() method from the Cello SDK to present a Floating Action Button (FAB) within your app. This FAB is pre-styled but may not perfectly match your app's look and feel.

import CelloSDK

​

Cello.showFab()

Custom launcher

If the default launcher does not fit your needs, you can implement your own custom launcher. This could be any UI element like a button, menu item, or even a gesture. To open the Referral component using a custom launcher, you can call Cello.openWidget().

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

For even more control, you can implement your own delegate conforming to the CelloDelegate protocol. This allows you to get callbacks for significant events in the Referral component.

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()

Initializes the Cello Referral Component in your product

import CelloSDK

​

Cello.initialize(for: "dev.cello.so", 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)

    }

}

Cello.updateToken()

Updates the token and also verifies it.

Cello.showFab()

Shows the Floating action button or bookmark that launches the Referral Component

import CelloSDK

​

Cello.showFab()

Cello.hideFab()

Hides the Floating action button or bookmark that launches the Referral Component

import CelloSDK

​

Cello.hideFab()

Cello.openWidget()

Opens Referral Component

import CelloSDK

​

Cello.openWidget()

Cello.hideWidget()

Hides Referral Component

import CelloSDK

​

Cello.hideWidget()

Cello.getActiveUcc()

A method to get an active ucc and invite link for the currently logged in user.

import CelloSDK

​

let result = Cello.getActiveUcc()

Cello.changeLanguage()

A method to change the language of the Referral component at runtime without re-initialising it.

import CelloSDK

​

Cello.changeLanguage(to: .de)

Cello.shutdown()

Shuts down connection to Cello and unmounts the component

import CelloSDK

​

Cello.shutdown()