# Banuba AR Face Filter (/en/realtime-media/marketplace/build/add-video-and-ar-effects/banuba/ios)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

This guide is provided by Banuba. Agora is planning a documentation upgrade program for all extensions on the marketplace. Please stay tuned.

By integrating Banuba Face AR SDK and Agora.io SDK you can enable augmented reality features in video calls such as face filters, face touch up filters and virtual backgrounds. You can find the integration examples below.

      
  
      
    ## Prerequisites [#prerequisites-1]

    * The latest Banuba SDK archive
    * [Banuba Extension files for iOS](https://www.banuba.com/faq/how-to-integrate-banuba-sdk-with-agora-sdk)
    * Banuba trial client token.

    To receive a trial token or a full commercial licence from Banuba - please fill in our form on [form on banuba.com](https://www.banuba.com/face-filters-sdk) website, or contact us via [info@banuba.com](mailto\:info@banuba.com).

    ## Integrate Banuba Face AR extension [#integrate-banuba-face-ar-extension-1]

    ### Get Started [#get-started-1]

    1. Get the following Banuba trial client token.
       To receive a trial token or a full commercial licence from Banuba - please fill in our form on [form on banuba.com](https://www.banuba.com/face-filters-sdk) website, or contact us via [info@banuba.com](mailto\:info@banuba.com).

    2. Execute `pod install` to get the Banuba SDK.

    3. Open the `BanubaAgoraFilters.xcworkspace` file in Xcode.

    4. Copy and Paste your Banuba client token into the appropriate section of `/BanubaAgoraFilters/Token.swift` with " " symbols. For example:

       ```swift
       let banubaClientToken = "Banuba Token"
       ```

    5. Visit agora.io to sign up and get the token, app and channel ID.

    6. Copy and Paste your agora token, app and chanel ID into appropriate section of `/BanubaAgoraFilters/Token.swift` with " " symbols. For example:

       ```swift
       internal let agoraAppID = "Agora App ID"
       internal let agoraClientToken = "Agora Token"
       internal let agoraChannelId = "Agora Channel ID"
       ```

    7. Donwload the needed effects from [here](https://docs.banuba.com/face-ar-sdk-v1/overview/demo_face_filters). This guarantees, that you will use the up-to-date version of the effects. The effects must be copied to the `agora-plugin-filters-ios -> BanubaAgoraFilters -> effects` folder.

    8. Open the `BanubaAgoraFilters.xcodeproj` project in Xcode and run the `BanubaAgoraFilters` target.

    If you have any problems with installing Agora frameworks with Swift Package Manager refer to this [page](https://github.com/AgoraIO/AgoraRtcEngine_iOS)

    #### Connecting Banuba SDK and AgoraRtcKit to your own project [#connecting-banuba-sdk-and-agorartckit-to-your-own-project]

    Connecting Banuba SDK to your project is similar to the steps in the Getting Started section. As for AgoraRtcKit, we advise to use Swift Package Manager. You should use the following settings:
    URL: `https://github.com/AgoraIO/AgoraRtcEngine_iOS.git`
    Version Rule: `Up to next minor`
    Version: `4.0.0`

    #### How to use `BanubaFiltersAgoraExtension` [#how-to-use-banubafiltersagoraextension-1]

    To control `BanubaFiltersAgoraExtension` with Agora libs look available keys listed below:

    ```swift
    public struct BanubaPluginKeys {
        public static let vendorName = "Banuba"
        public static let extensionName = "BanubaFilter"
        public static let loadEffect = "load_effect"
        public static let unloadEffect = "unload_effect"
        public static let setEffectsPath = "set_effects_path"
        public static let setToken = "set_token"
    }
    ```

    To enable/disable `BanubaFiltersAgoraExtension` use the following method:

    ```swift
    import BanubaFiltersAgoraExtension

    agoraKit?.enableExtension(
        withVendor: BanubaPluginKeys.vendorName,
        extension: BanubaPluginKeys.extensionName,
        enabled: true
    )
    ```

    Before applying an effect on your video you have to initialize `BanubaFiltersAgoraExtension` with the path to effects and banuba client token. Look how it can be achieved:

    ```swift
    agoraKit?.setExtensionPropertyWithVendor(
        BanubaPluginKeys.vendorName,
        extension: BanubaPluginKeys.extensionName,
        key: BanubaPluginKeys.setEffectsPath,
        value: "place_path_to_effects_folder_here"
    )

    agoraKit?.setExtensionPropertyWithVendor(
        BanubaPluginKeys.vendorName,
        extension: BanubaPluginKeys.extensionName,
        key: BanubaPluginKeys.setToken,
        value: "place_your_banuba_token_here".trimmingCharacters(in: .whitespacesAndNewlines)
    )
    ```

    After those steps you can tell `BanubaFiltersAgoraExtension` to enable or disable the mask:

    ```swift
    agoraKit?.setExtensionPropertyWithVendor(
        BanubaPluginKeys.vendorName,
        extension: BanubaPluginKeys.extensionName,
        key: BanubaPluginKeys.loadEffect,
        value: "put_effect_name_here"
    )

    agoraKit?.setExtensionPropertyWithVendor(
        BanubaPluginKeys.vendorName,
        extension: BanubaPluginKeys.extensionName,
        key: BanubaPluginKeys.unloadEffect,
        value: " "
    )
    ```

    If the mask has parameters and you want to change them, you can do it the next way:

    ```swift
    agoraKit?.setExtensionPropertyWithVendor(
        BanubaPluginKeys.vendorName,
        extension: BanubaPluginKeys.extensionName,
        key: BanubaPluginKeys.evalJSMethod,
        value: string
    )
    ```

    `string` must be a string with method's name and parameters. You can find an example in our [documentation](https://docs.banuba.com/face-ar-sdk-v1/effect_api/face_beauty).

    #### How to build `BanubaFiltersAgoraExtension` [#how-to-build-banubafiltersagoraextension]

    To build the `BanubaFiltersAgoraExtension` manually, please follow the steps bellow:

    1. Execute `pod install` to get the Banuba SDK.

    2. Open the `BanubaAgoraFilters.xcworkspace` file in Xcode.

    3. Choose **File->Packages->Reset Package Cashes** from Xcode menu.

    4. Build the target `BanubaFiltersAgoraExtension`. It will be built with your Swift version. After this you should open the section **Products** in the **Project Navigator** (the left part of the Xcode screen). Click on the `BanubaFiltersAgoraExtension` with the right click of the mouse and choose **Show in Finder**. Copy the `BanubaFiltersAgoraExtension.framework` from the folder.

    5. Then put the framework to the `/Frameworks` folder of the `BanubaAgoraFilters.xcodeproj` (or of your project). Then you can build BanubaAgoraFilters or your project.

    The reconnection of the `BanubaFiltersAgoraExtension.framework` to the example project may be required. To do it, you should remove the `BanubaFiltersAgoraExtension.framework` from the Project Settings: **General-> Frameworks, Libraries and Embedded Content**. Then you should drag\&drop the `BanubaFiltersAgoraExtension.framework` to this section. You should choose **Embed\&Sign** for this framework.

    #### Effects managing [#effects-managing-1]

    To retrieve effects list use the following code:

    ```swift
    let effectsPath = BanubaEffectsManager.effectsURL.path
    let effectsService = EffectsService(effectsPath: effectsPath)
    let effectViewModels =
        effectsService
        .getEffectNames()
        .sorted()
        .compactMap { effectName in
            guard let effectPreviewImage = effectsService.getEffectPreview(effectName) else {
                return nil
            }

            let effectViewModel = EffectViewModel(image: effectPreviewImage, effectName: effectName)
            return effectViewModel
        }
    ```

    `EffectViewModel` has the following properties:

    ```swift
    class EffectViewModel {
        let image: UIImage
        let effectName: String?
        var cancelEffectModel: Bool {
            return effectName == nil
        }
    }
    ```

    ## Run the demo [#run-the-demo-1]

    * [Demo app (distribution by request via support channels at the bottom of the page)](https://appcenter.ms/users/andrei.sak-banuba.com/apps/BanubaAgoraExtensionSample)
    * [Github repository](https://github.com/Banuba/agora-plugin-filters-ios)