⚠️ Due to the end of the Cross Promotion Platform, this repository is now deprecated.

CrossDK 4.1.2

##Table of contents :

• UIKit
• SwiftUI
• Objective-C

Overview

CrossDK is a solution belonging to Adikteev. The goal is to allow its users to cross-promote their application catalog through the CrossDKOverlay class.

Requirements

iOS version >= 10.0

CrossDK is available with iOS 10 minimal target version but the CrossDKOverlay is only available since iOS 14. CrossDK provides support in order to handle cases where the CrossDKOverlay is not available (see Overlay Delegate)

Installation

Swift Package Manager

Note: Instructions below are for using SPM without the Xcode UI. It's easier to go to File > Swift Packages > Add Package Dependencies... and add CrossDK through there.

To integrate using Apple's Swift Package Manager, without Xcode integration, add the following as a dependency to your Package.swift:

.package(url: "https://github.com/Adikteev/crossdk-ios", .upToNextMajor(from: "4.0.1"))

and then specify "CrossDK" as a dependency of the Target in which you wish to use CrossDK. Here's an example PackageDescription:

// swift-tools-version:5.3
import PackageDescription

let package = Package(
    name: "MyPackage",
    products: [
        .library(
            name: "MyPackage",
            targets: ["MyPackage"]),
    ],
    dependencies: [
        .package(url: "https://github.com/Adikteev/crossdk-ios", .upToNextMajor(from: "4.0.1"))
    ],
    targets: [
        .target(
            name: "MyPackage",
            dependencies: ["CrossDK"])
    ]
)

CocoaPods

Add the following entry to your Podfile for CrossDK:

pod 'CrossDK'

Then run pod install.

Manually

• Clone CrossDK's repository wherever you like in your project. For this example we will clone it in a CrossDK-release directory

$ git clone https://github.com/Adikteev/crossdk-ios.git CrossDK-release

OR

$ git clone ssh://[email protected]:Adikteev/crossdk-ios.git CrossDK-release

• Open the new CrossDK-release/Products folder, and drag the CrossDK.xcframework into the Project Navigator of your application's Xcode project. You can put it anywhere inside your project, just make sure you select any target that needs to use CrossDK.

• And that's it!

XCode will automatically add CrossDK.xcframework to your Link Binary With Libraries Build Phase.

Usage

In any file you'd like to use CrossDK in, don't forget to import the framework with import CrossDK.

SwiftUI and Objective-C supports

In order to cover a majority of projects, the CrossDKOverlay class is developed in UIKit :

• see SwiftUI support here
• see Objective-C support here

UIKit

See an example in the CrossDK-demo UIKit project.

Configuration

In order to display an overlay properly, CrossDK requires a few informations. Since CrossDK won't work without these, you should set them up as soon as possible. In the following example, we use the setup function inside AppDelegate's application launch but it's up to you to set it up wherever you like.

import CrossDK

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    [...]

    func application(_ application: UIApplication, 
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
                     
        CrossDKConfig.shared.setup(appId: <YOUR APP ID>,
                                   apiKey: <YOUR API KEY>,
                                   userId: <USER'S ID (optional)>)

        return true
    }
    
    [...]
}

Overlay Usage

All you need to do in order to display an overlay is to retrieve your UIWindow object and call the display function. Then call it in the viewDidAppear. Here are the configurations for each overlay format :

• .banner : settle its position between .bottom or .bottomRaised
• .mid_size : settle its position between .bottom or .bottomRaised, with or without a close button
• .interstitial : settle it with or without a close button, with or without a rewarded

import CrossDK

final class SomeViewController: UIViewController {
    private let crossDKOverlay = CrossDKOverlay()
    
    private func displayOverlay() {
        guard let window = view.window else { return }

        crossDKOverlay.display(window: window, format: .mid_size, position: .bottom, withCloseButton: true, isRewarded: false)
    }
}

You can also preload recommendation before displaying it on screen, this is particularly useful when having large assets(video) which takes time to display. Preload should be launched before showing ads on screen in order to leave enough time to video to be prepared. Use the interface CrossDKOverlayDelegate to get notified when load finishes.

A recommendation is available '30min' after its preload, when this delay passed the view becomes expired and can no longer be showed on screen.

import CrossDK

final class SomeViewController: UIViewController {
    private let crossDKOverlay = CrossDKOverlay()
    
    private func loadOverlay() {
        guard let window = view.window else { return }

        crossDKOverlay.load(window: window, format: .mid_size, position: .bottom, withCloseButton: true, isRewarded: false)
    }
}
extension SomeViewController: CrossDKOverlayDelegate {
    [...]
    
     func overlayDidPreload() {
        crossDKOverlay.display()
    }
    
    func overlayPreloadFailure() {
        // In preloading failure
    }
    
    func overlayPreloadExpired() {
        // The preload has expired
    }
}

A public variable is available in CrossDKConfig : deviceId, to use custom device to try your recommendations using another device id than yours. Set it before crossDKOverlay.display function call.

    CrossDKConfig.shared.deviceId = "My custom device ID"
    crossDKOverlay.display(window: window, format: .banner, position: .bottom, withCloseButton: false, isRewarded: false)

Overlay Delegate

Additionally, a delegate is available if you want to monitor what is happening with the CrossDKOverlay.

Since CrossDKOverlay is only available with iOS 14 or higher, you might want, for example, to do something else if the overlay display is unavailable.

import CrossDK

final class SomeViewController: UIViewController {
    private let crossDKOverlay = CrossDKOverlay()
    
    override func viewDidLoad() {
        super.viewDidLoad()
        crossDKOverlay.delegate = self
    }
}

extension SomeViewController: CrossDKOverlayDelegate {
    [...]
    
    func overlayUnavailable(error: CrossDKOverlay.OverlayError) {
        switch error {
        case .unsupportedOSVersion:
            // Do something for old iOS versions.
        case .unavailableWindowScene:
            
        case .unavailableRecommendation:
            
        case .noConfiguration:
            
        @unknown default:
            
        }
    }
}

CrossDK Debug mode:

You can enable the debug mode on the SDK to generate logs in the console. This can be done by setting the logLevel in CrossDKConfig class:

import CrossDK

CrossDKConfig.shared.setLog(level: LogLevel.verbose)

• LogLevel.verbose: for verbose logging
• LogLevel.error: for error logging
• LogLevel.none: for disabling logger

We recommend setting up this config before initializing the SDK.

SwiftUI support

In this section, we will see how to integrate it into a SwiftUI project.

See an example in the CrossDK-demo SwiftUI project.

Configuration

In order to display an overlay properly, CrossDK requires a few informations. Since CrossDK won't work without these, you should set them up as soon as possible. In the following example, we use the setup function inside AppDelegate's (create the swift file in your SwiftUI project) application launch but it's up to you to set it up wherever you like.

import CrossDK

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    [...]

    func application(_ application: UIApplication, 
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
                     
        CrossDKConfig.shared.setup(appId: <YOUR APP ID>,
                                   apiKey: <YOUR API KEY>,
                                   userId: <USER'S ID (optional)>)

        return true
    }
    
    [...]
}

In your App scene, use the UIApplicationDelegateAdaptor property wrapper to tell SwiftUI it should use your AppDelegate class for the application delegate.

import SwiftUI

@main
struct SwiftUIApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Overlay Usage

All you need to do in order to display an overlay is to retrieve your UIWindow object and call the display function. Then call it in the viewDidAppear. Here are the configurations for each overlay format :

• .banner : settle its position between .bottom or .bottomRaised
• .mid_size : settle its position between .bottom or .bottomRaised, with or without a close button
• .interstitial : settle it with or without a close button, with or without a reward

Let’s create a UIViewController subclass named SomeViewController and add some methods to :

• display an Overlay (to call in the viewDidAppear)
• dismiss the SomeViewController (to call in the CrossDKOverlayDelegate)

import CrossDK

final class SomeViewController: UIViewController {
    private let crossDKOverlay = CrossDKOverlay()
    
    private func displayOverlay() {
        guard let window = view.window else { return }

        crossDKOverlay.display(window: window, format: .mid_size, position: .bottom, withCloseButton: true, isRewarded: false)
    }
    
    private func dismissCrossDKViewController() {
        dismiss(animated: true, completion: nil)
    }
}

You can also preload recommendation before displaying it on screen, this is particularly useful when having large assets(video) which takes time to display. Preload should be launched before showing ads on screen in order to leave enough time to video to be prepared. Use the interface CrossDKOverlayDelegate to get notified when load finishes.

A recommendation is available '30min' after its preload, when this delay passed the view becomes expired and can no longer be showed on screen.

import CrossDK

final class SomeViewController: UIViewController {
    private let crossDKOverlay = CrossDKOverlay()
    
    private func loadOverlay() {
        guard let window = view.window else { return }

        crossDKOverlay.load(window: window, format: .mid_size, position: .bottom, withCloseButton: true, isRewarded: false)
    }
}
extension SomeViewController: CrossDKOverlayDelegate {
    [...]
    
     func overlayDidPreload() {
        crossDKOverlay.display()
    }
    
    func overlayPreloadFailure() {
        // In preloading failure
    }
    
    func overlayPreloadExpired() {
        // The preload has expired
    }
}

Overlay Delegate

Additionally, a delegate is available if you want to monitor what is happening with the CrossDKOverlay.

Now, call the dismissCrossDKViewController() method in the CrossDKOverlayDelegate :

import CrossDK

final class SomeViewController: UIViewController {
    private let crossDKOverlay = CrossDKOverlay()
    
    override func viewDidLoad() {
        super.viewDidLoad()
        crossDKOverlay.delegate = self
    }
}

extension SomeViewController: CrossDKOverlayDelegate {
    [...]
    
    func overlayDidFinishDismissal() {
        dismissCrossDKViewController()
    }
}

ContentView :

To use this SomeViewController with SwiftUI, we need to call UIViewControllerRepresentable ! Let’s create our SwiftUISomeViewController which conforms to UIViewControllerRepresentable :

struct SwiftUISomeViewController: UIViewControllerRepresentable {
    func makeUIViewController(context: Context) -> CrossDKOverlayViewController {
        return SomeViewController()
    }

    func updateUIViewController(_ uiViewController: SomeViewController, context: Context) {

    }
}

To clear the UIViewControllerRepresentable backgroud, let's create a ClearBackgroundView :

struct ClearBackgroundView: UIViewRepresentable {
    func makeUIView(context: Context) -> UIView {
        let view = UIView()
        DispatchQueue.main.async {
            view.superview?.superview?.backgroundColor = .clear
        }
        
        return view
    }

    func updateUIView(_ uiView: UIView, context: Context) {}
}

Now, create a View to display the overlay independently :

struct CrossDKOverlayView: View {
    @State private var isVCPresented = false

    internal var body: some View {
        Color.clear
            .frame(width: 0.0, height: 0.0, alignment: .center)
            .onAppear(perform: {
                self.isVCPresented = true
            })
            .fullScreenCover(isPresented: $isVCPresented) {
                ZStack {
                    VStack {
                        SwiftUISomeViewController()
                    }
                }
                .background(ClearBackgroundView())
            }
    }
}

And add it in the ContentView :

struct ContentView: View {
    var body: some View {
        CrossDKOverlayView()
    }
}

That’s all you need to know !

Objective-C support

In this section, we will see how to integrate it into a Objective-C project.

See an example in the CrossDK-demo Objective-C project.

Configuration

AppDelegate.h :

You should #import "CrossDK/CrossDK-Swift.h" to use CrossDK.

AppDelegate.m :

In order to display an overlay properly, CrossDK requires a few informations. Since CrossDK won't work without these, you should set them up as soon as possible. In the following example, we use the setup function inside AppDelegate's application launch but it's up to you to set it up wherever you like.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [CrossDKConfig.shared setupWithAppId:<#(NSString * _Nonnull)#> apiKey:<#(NSString * _Nonnull)#> userId:<#(NSString * _Nullable)#>];
    return YES;
}

Note: userId being _Nullable, you can put nil if needed.

Overlay Usage

ViewController.h :

You should #import "CrossDK/CrossDK-Swift.h" to use CrossDK.

ViewController.m :

All you need to do in order to display an overlay is to retrieve your UIWindow object and call the display function. Then call it in the viewDidAppear. Here are the configurations for each overlay format :

• .banner : settle its position between .bottom or .bottomRaised
• .mid_size : settle its position between .bottom or .bottomRaised, with or without a close button
• .interstitial : settle it with or without a close button, with or without a reward

@interface CrossDKViewController ()
    @property (strong, nonatomic) CrossDKOverlay* crossDKOverlay;
@end

- (void)displayOverlay {
    UIWindow* window = self.view.window;
    if (window != nil) {
        [_crossDKOverlay displayWithWindow:window format:OverlayFormatMid_size position:OverlayPositionBottom withCloseButton:true isRewarded:false];
    }
}

- (void)viewWillAppear:(BOOL)animated {
    [super viewDidAppear:animated];

    [self displayOverlay];
}

Overlay Delegate

Additionally, a delegate is available if you want to monitor what is happening with the CrossDKOverlay.

Since CrossDKOverlay is only available with iOS 14 or higher, you might want, for example, to do something else if the overlay display is unavailable.

First, add <CrossDKOverlayDelegate> beside @interface CrossDKViewController () and call it in the viewDidLoad.

@interface CrossDKViewController () <CrossDKOverlayDelegate>
    @property (strong, nonatomic) CrossDKOverlay* crossDKOverlay;
@end

- (void)viewDidLoad {
    [super viewDidLoad];

    _crossDKOverlay = [[CrossDKOverlay alloc] init];
    _crossDKOverlay.delegate = self;
}

And now, you can access to the CrossDKOverlayDelegate.

[...]

- (void)overlayUnavailableWithError:(enum OverlayError)error {
    switch(error) {
        case OverlayErrorUnsupportedOSVersion:
            NSLog(@"Overlay error: unsupported iOS Version");
            break;
        case OverlayErrorUnavailableWindowScene:
            NSLog(@"Overlay error: unavailable window scene");
            break;
        case OverlayErrorUnavailableRecommendation:
            NSLog(@"Overlay error: unavailable recommendation");
            break;
        case OverlayErrorNoConfiguration:
            NSLog(@"Overlay error: no configuration");
            break;
    }
}

You can also preload recommendation before displaying it on screen, this is particularly useful when having large assets(video) which takes time to display. Preload should be launched before showing ads on screen in order to leave enough time to video to be prepared. Use the interface CrossDKOverlayDelegate to get notified when load finishes.

A recommendation is available '30min' after its preload, when this delay passed the view becomes expired and can no longer be showed on screen.

- (void)loadOverlay {
    UIWindow* window = self.view.window;
    if (window != nil) {
        [_crossDKOverlay loadWithWindow:window format:OverlayFormatMid_size position:OverlayPositionBottom withCloseButton:true isRewarded:false];
    }
    
[...]

- (void)overlayDidPreload() {
     [_crossDKOverlay display];
    }
    
- (void)overlayPreloadFailure() {
     // In preloading failure
    }
    
- (void)overlayPreloadExpired() {
      // The preload has expired
    }
}

That’s all you need to know !