diff --git a/extensions-marketplace/develop/integrate/banuba.mdx b/extensions-marketplace/develop/integrate/banuba.mdx index 1e726f136..2eddb9313 100644 --- a/extensions-marketplace/develop/integrate/banuba.mdx +++ b/extensions-marketplace/develop/integrate/banuba.mdx @@ -42,158 +42,162 @@ To receive a trial token or a full commercial licence from Banuba - please fill -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. +1. Visit [Agora](https://www.agora.io/en/) to sign up and get the app id, client token and channel id. Please consult with [Agora documentation about account management](https://docs.agora.io/en/voice-calling/reference/manage-agora-account) to find out exactly how mentioned IDs are created. -3. Open the `BanubaAgoraFilters.xcworkspace` file in Xcode. +2. Activate the [Banuba Face AR SDK extension](https://console.agora.io/marketplace/extension/introduce?serviceName=banuba) to get the app key and app secret. Please check out the [extension integration documentation](https://docs.agora.io/en/video-calling/develop/use-an-extension?platform=ios) if you have any questions regarding this step. -4. Copy and Paste your Banuba client token into the appropriate section of `/BanubaAgoraFilters/Token.swift` with “ ” symbols. For example: +3. Open a terminal and run the following command to clone the project to your computer: - ```` swift - let banubaClientToken = "Banuba Token" - ```` + ```sh + git clone https://github.com/Banuba/agora-plugin-filters-ios.git + ``` -5. Visit agora.io to sign up and get the token, app and channel ID. +4. In the terminal open the project directory and run the 'pod install' command to get the Banuba and Agora SDKs and plugin framework: + ```sh + cd agora-plugin-filters-ios/ + pod install + ``` -6. Copy and Paste your agora token, app and chanel ID into appropriate section of `/BanubaAgoraFilters/Token.swift` with “ ” symbols. For example: +5. Open the `BanubaAgoraFilters.xcworkspace` file in Xcode. - ```` swift +6. Copy and paste your Agora token, app and channel ID to the appropriate section of `/BanubaAgoraFilters/Token.swift`. 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. +7. Copy and Paste your Banuba extension credentials received from the sales representative to the appropriate section of `/BanubaAgoraFilters/Token.swift` with “ ” symbols. For example: + + ``` swift + let appKey = "Banuba Extension App Key" + let appSecret = "Banuba Extension App Secret" + ``` -8. Open the `BanubaAgoraFilters.xcodporj` project in Xcode and run the `BanubaAgoraFilters` target. +8. Download 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. -If you have any problems with installing Agora frameworks with Swift Package Manager refer to this page +9. Run the `BanubaAgoraFilters` target. #### 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` +Connecting Banuba SDK to your project is similar to the steps in the `Getting Started` section. -#### How to use `BanubaFiltersAgoraExtension` +As for `AgoraRtcKit` you can install it using either Swift Package Manager of Cocoapods. You should use the following settings for SPM: +URL: `https://github.com/AgoraIO/AgoraRtcEngine_iOS` +Version Rule: `Exact` +Version: `4.0.1` -To control `BanubaFiltersAgoraExtension` with Agora libs look available keys listed below: +In case of Cocoapods add the following line to your Podfile: +```ruby +pod 'AgoraRtcEngine_iOS', '4.0.1' +``` -````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" -} -```` +#### Plugin installation -To enable/disable `BanubaFiltersAgoraExtension` use the following method: +The `BanubaFiltersAgoraExtension` plugin can be installed with Cocoapods. Simply add the following line to your Podfile: +```ruby +pod 'BanubaFiltersAgoraExtension', '2.0.0' +``` +Please make sure that you have also added our custom Podspecs source to your Podfile: +```ruby +source 'https://github.com/sdk-banuba/banuba-sdk-podspecs.git' +``` -````swift -import BanubaFiltersAgoraExtension +Alternatively you can also install the extension by downloading the prebuilt `xcframework` from [here](https://github.com/Banuba/banuba-filters-agora-extension-framework) and manually linking it to your project. -agoraKit?.enableExtension( - withVendor: BanubaPluginKeys.vendorName, - extension: BanubaPluginKeys.extensionName, - enabled: true -) -```` +#### How to use `BanubaFiltersAgoraExtension` -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: +To control `BanubaFiltersAgoraExtension` with Agora libs use the following keys from `BanubaPluginKeys.h` file: +```objc +extern NSString * __nonnull const BNBKeyVendorName; +extern NSString * __nonnull const BNBKeyExtensionName; +extern NSString * __nonnull const BNBKeyLoadEffect; +extern NSString * __nonnull const BNBKeyUnloadEffect; +extern NSString * __nonnull const BNBKeySetAppKey; +extern NSString * __nonnull const BNBKeySetAppSecret; +extern NSString * __nonnull const BNBKeySetEffectsPath; +extern NSString * __nonnull const BNBKeyEvalJSMethod; +``` -````swift -agoraKit?.setExtensionPropertyWithVendor( - BanubaPluginKeys.vendorName, - extension: BanubaPluginKeys.extensionName, - key: BanubaPluginKeys.setEffectsPath, - value: "place_path_to_effects_folder_here" +To enable/disable `BanubaFiltersAgoraExtension` use the following method: +```swift +import BanubaFiltersAgoraExtension +agoraKit?.enableExtension( + withVendor: BNBKeyVendorName, + extension: BNBKeyExtensionName, + enabled: true ) +``` -agoraKit?.setExtensionPropertyWithVendor( - BanubaPluginKeys.vendorName, - extension: BanubaPluginKeys.extensionName, - key: BanubaPluginKeys.setToken, - value: "place_your_banuba_token_here".trimmingCharacters(in: .whitespacesAndNewlines) -) -```` +Before applying an effect to your video you have to initialize `BanubaFiltersAgoraExtension` with the path to effects and extension credentials (app key and app secret). Look how it can be achieved: +```swift +agoraKit?.setExtensionPropertyWithVendor(BNBKeyVendorName, + extension: BNBKeyExtensionName, + key: BNBKeySetEffectsPath, + value: BanubaEffectsManager.effectsURL.path) + +agoraKit?.setExtensionPropertyWithVendor(BNBKeyVendorName, + extension: BNBKeyExtensionName, + key: BNBKeySetAppKey, + value: appKey) + +agoraKit?.setExtensionPropertyWithVendor(BNBKeyVendorName, + extension: BNBKeyExtensionName, + key: BNBKeySetAppSecret, + value: appSecret) +``` After those steps you can tell `BanubaFiltersAgoraExtension` to enable or disable the mask: -````swift +```swift agoraKit?.setExtensionPropertyWithVendor( - BanubaPluginKeys.vendorName, - extension: BanubaPluginKeys.extensionName, - key: BanubaPluginKeys.loadEffect, + BNBKeyVendorName, + extension: BNBKeyExtensionName, + key: BNBKeyLoadEffect, value: "put_effect_name_here" ) - + agoraKit?.setExtensionPropertyWithVendor( - BanubaPluginKeys.vendorName, - extension: BanubaPluginKeys.extensionName, - key: BanubaPluginKeys.unloadEffect, + BNBKeyVendorName, + extension: BNBKeyExtensionName, + key: BNBKeyUnloadEffect, value: " " ) -```` +``` If the mask has parameters and you want to change them, you can do it the next way: -````swift +```swift agoraKit?.setExtensionPropertyWithVendor( - BanubaPluginKeys.vendorName, - extension: BanubaPluginKeys.extensionName, - key: BanubaPluginKeys.evalJSMethod, + BNBKeyVendorName, + extension: BNBKeyExtensionName, + key: BNBKeyEvalJSMethod, 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` - -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. +) +``` +`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). #### Effects managing To retrieve effects list use the following code: -````swift +```swift let effectsPath = BanubaEffectsManager.effectsURL.path let effectsService = EffectsService(effectsPath: effectsPath) -let effectViewModels = - effectsService +let effectViewModels = effectsService .getEffectNames() .sorted() .compactMap { effectName in guard let effectPreviewImage = effectsService.getEffectPreview(effectName) else { - return nil + return nil } - let effectViewModel = EffectViewModel(image: effectPreviewImage, effectName: effectName) return effectViewModel - } -```` - -`EffectViewModel` has the following properties: + } +``` -````swift +`EffectViewModel` has the next properties: +```swift class EffectViewModel { let image: UIImage let effectName: String? @@ -201,8 +205,7 @@ class EffectViewModel { return effectName == nil } } -```` - +```