Skip to main content

​
iOS SDK

Your project must target iOS 10 or later. Swift projects should use Swift 4.2 or later, and CocoaPods 1.8.1 or later is required.
Add a package by selecting File → Add Packages… in Xcode’s menu bar.Search for the BoxoSDK using the repo’s URL:
https://github.com/Appboxo/boxo-ios-spm.git
Next, set the Dependency Rule to be Up to Next Major Version.Then, select Add Package.
Import Boxo SDK in your ViewController:
import BoxoSDK
Initialize Boxo in your app by configuring a Boxo shared instance. Remember to replace client_id field with your client_id.
let config = Config(clientId: "client_id")
Boxo.shared.setConfig(config: config)
To launch the miniapp, you will need a UIViewController:

​
UIKit

To open miniapp write this code in your UIViewController:
let miniapp = Boxo.shared.getMiniapp(appId: "app_id")
miniapp.open(viewController: self)

​
SwiftUI

If you are using SwiftUI, you need to access the current UIViewController. There are many ways to obtain a UIViewController. Here is one of them:
struct ViewControllerFinder: UIViewControllerRepresentable {
    var onViewControllerFound: (UIViewController) -> Void

    func makeUIViewController(context: Context) -> UIViewController {
        let viewController = UIViewController()
        DispatchQueue.main.async {
            self.onViewControllerFound(viewController)
        }
        return viewController
    }

    func updateUIViewController(_ uiViewController: UIViewController, context: Context) {}
}
...
struct ContentView: View {
    @State private var currentViewController: UIViewController?
    
    var body: some View {
        ViewControllerFinder { viewController in
            currentViewController = viewController
        }
        Button(action: {
            guard let currentViewController = currentViewController else { return }

            let miniapp = Boxo.shared.getMiniapp(appId: "app_id")
            miniapp.open(viewController: currentViewController)
        }) {
            Text("Open miniapp")
        }
    }
}
Miniapp lifecycle events allow you to monitor key activities, such as onLaunch, onResume, onPause, onClose, and onError. These events help track the miniapp’s behavior throughout its usage lifecycle.
miniapp.delegate = self
...
extension ViewController: MiniappDelegate {
    func onLaunch(miniapp: Miniapp) {
        print("onLaunchMiniapp: \(miniapp.appId)")
    }

    func onResume(miniapp: Miniapp) {
        print("onResumeMiniapp: \(miniapp.appId)")
    }

    func onPause(miniapp: Miniapp) {
        print("onPauseMiniapp: \(miniapp.appId)")
    }

    func onClose(miniapp: Miniapp) {
        print("onCloseMiniapp: \(miniapp.appId)")
    }

    func onError(miniapp: Miniapp, message: String) {
        print("onErrorMiniapp: \(miniapp.appId) message: \(message)")
    }
}
Dark mode support for splash screen and other native components used inside miniapp.
Boxo.shared.setConfig(config: Config(clientId: "client_id", theme: .Dark)) //[Dark, Light, System] System - by default
Use MiniappConfig to override theme of miniapp.
miniapp.setConfig(config: MiniappConfig(theme: .Dark))
Setup onAuth listener for login event from Miniapp
miniapp.delegate = self
...
extension ViewController : MiniappDelegate {
  func onAuth(miniapp: Miniapp) {
    miniapp.setAuthCode(authCode: "[AUTH_CODE]")
  }
}
When host app user logs out, it is highly important to clear all miniapp storage data. To clear call .logout():
Boxo.shared.logout()
To listen for any URL change events, use .setUrlChangeListener:
miniapp.delegate = self
...
extension ViewController: MiniappDelegate {
    func didChangeUrlEvent(miniapp: Miniapp, url: URL) {
        // Listen for search URL
        if url.path.components(separatedBy: "/").contains("search") {
            print("Search url: \(url)")
        }
    }
}
To append custom data params to miniapp URL use .params:
let miniapp = Boxo.shared.getMiniapp(appId: "app_id")
let miniappConfig = MiniappConfig(theme: .System)
// Set params that will be appended to miniapp's url
// Ex. https://google.com/?name=Orave
miniappConfig.setExtraParams(extraParams: ["name" : "Orave"])
miniapp.setConfig(config: miniappConfig)
You can add your custom action menu item to existing default action menu item by defining .setCustomActionMenuItemImage
let miniapp = Boxo.shared.getMiniapp(appId: "app_id")
let miniappConfig = MiniappConfig(theme: .System)
// Set third custom action menu item
// It is hidden by default
miniappConfig.setCustomActionMenuItemImage(image: UIImage(named: "ic_custom_action_button"))
miniapp.setConfig(config: miniappConfig)
...
extension ViewController : MiniappDelegate {
    func didSelectCustomActionMenuItemEvent(miniapp: Miniapp) {
        //show any custom dialog when custom action menu item is clicked
    }
}
To show/hide custom action menu item use miniapp.showCustomActionMenuItem() and miniapp.hideCustomActionMenuItem()
Fetch the complete catalog of available miniapps with detailed metadata. This operation returns:
  • Basic miniapp information (id, name, description)
  • Logo
  • Category
Boxo.shared.getMiniapps { miniapps, error in
    miniapps.forEach { data in
        print(data.appId)
        print(data.name)
        print(data.longDescription)
        print(data.logo)
        print(data.category)
    }
}

let miniapp = Boxo.shared.getMiniapp(appId: "app_id")
            
let miniappConfig = MiniappConfig()
miniappConfig.enableSplash(isSplashEnabled: false) // to skip splash screen. if enabled, the splash screen will be hidden when 50% of web content is loaded. Otherwise, when the web page starts loading. By default is enabled.
miniapp.setConfig(config: miniappConfig)

miniapp.open(viewController: self)
sandboxMode: it should open miniapps in “Approved” and “InTesting” statuses List of miniapps returns:
  • when true, miniapps in “Approved” and “InTesting” statuses
  • when false, miniapps only in “Approved” status
let config = Config(clientId: "CLIENT_ID")
config.sandboxMode = true //by default false
Boxo.shared.setConfig(config: config)
Customize the animation effects to enhance the user experience by setting the appropriate page transition animation when opening a miniapp.You can choose from the following page animations:
  • LEFT_TO_RIGHT - The miniapp slides in from the left side of the screen to the right.
  • RIGHT_TO_LEFT - The miniapp slides in from the right side of the screen to the left.
  • BOTTOM_TO_TOP- The miniapp slides in from the bottom of the screen to the top.
  • TOP_TO_BOTTOM - The miniapp slides in from the top of the screen to the bottom.
  • FADE_IN - The miniapp fades in gradually from completely transparent to opaque.
The BOTTOM_TO_TOP animation is the default page transition effect. You can easily change the animation to any of the other available options based on the user experience you want to provide.
let config = MiniappConfig()
config.pageAnimation = PageAnimation.RIGHT_TO_LEFT

let miniapp = Boxo.shared.getMiniapp(appId: "app_id")
miniapp.setConfig(config: config)
miniapp.open(viewController: self)