Advertising SDK Standard iOS ​

iOS Ads SDK (далее SDK) предназначено для монетизации рекламного инвентаря в ваших приложениях.

SDK предоставляет возможность загрузки и отображения следующих типов рекламных креативов в вашем приложении:

Баннеры:

• HTML Banner (html рекламный контент) - баннеры, представляющие собой HTML-разметку, встраивается внутрь CreativeView иерархии. Для рендеринга HTML (под капотом) используется WebKit > WKWebView (встроенный движок браузера), который рендерид и отображает HTML код.

• Image Banner (рекламный контент, представленный в виде картиники) - в качестве рекламного контента, встраивается простая картинка.

• Media Banner (video, audio) - медиа рекламный контент, базируется на VAST спецификации.

Для просмотра детальной информации смотри раздел Показ баннерной рекламы.

Товарные:

• Товарный креатив - специальный тип рекламного креатива для RetailMedia платформ, использующий в своей основе SKU идентификатор товара в RetailMedia платформе.

Для просмотра детальной информации смотри раздел Показ товарных креативов.

Версия SDK:

Демо: Advertising SDK Example

Репозиторий со стабильным релизом: Advertising SDK Standard

Требования

• Swift 5 и выше
• iOS 12 и выше

Установка ​

Подключение CocoaPods зависимости.

Для использования iOS Ads SDK необходимо установить следующие зависимось в Podfile файле вашего проекта:

pod 'SAAdvertisingSDKStandard'

или

pod 'SAAdvertisingSDKStandard', :git => 'https://github.com/solutionarchitectstech/mobile_sdk_release_ios.git', :tag => '{{ version }}'

Инициализация SDK ​

Инициализация библиотеки и создание рекламных мест выполняется разработчиком вызовом метода TechAdvetrising.initialize() в момент запуска приложения или в момент авторизации пользователя.

Вам необходимо передать (в качестве параметров инициализации) initConfig или remoteConfigUrl. Если вы передадите оба объектаб то initConfig будет иметь больший приоритет.

// Если вы планируете использовать внутренний 'CUSTOM' протокол SDK.
TechAdvertising.initialize(options: TechAdvertisingOptions(
    sessionId: "YOUR_SESSION_ID",
    storeUrl: "https://apps.apple.com/us/app/myapp/id12345678",
    initConfig: .init(
        core: .init(
            bannerUrl: "https://YOUR_BANNER_CREATIVE_ENDPOINT",
            productUrl: "https://YOUR_PRODUCT_CREATIVE_ENDPOINT"
        )
    ),
    debugMode: true,
    httpHeaders: [
        "Authorization": "Bearer CUSTOM_AUTH_TOKEN"
    ]
))

// В случае, если вы хотите использовать 'OpenRTB' протокол внутри SDK.
TechAdvertising.initialize(options: TechAdvertisingOptions(
    sessionId: "YOUR_SESSION_ID",
    storeUrl: "https://apps.apple.com/us/app/myapp/id12345678",
    transactionProtocol: .OPEN_RTB(
        publisherId: "YOUR_PUBLISHER_ID", // Optional, set this up here if you have it
        appContentType: .OTHER, // Optional
        appContentProductionQuality: .PROFESSIONALLY_PRODUCED, // Optional
        appContentMediaRating: .ALL_AUDIENCES // Optional
    ),
    initConfig: .init(
        core: .init(
            bannerUrl: "https://YOUR_OPENRTB_ENDPOINT"
        )
    ),
    debugMode: true,
    httpHeaders: [
        "Authorization": "Bearer CUSTOM_AUTH_TOKEN"
    ]
))

// Если ваше приложение инициализирует SDK (в рамках жизненного цикла) после того как,
// пользователь авторизовался, то вы можете выставить уникальный идетификатор
// авторизованного пользователя здесь же после инициализации. В этом случае используйте
// следующую строку как пример.
// В противном случае (рекоммендуемый вариант), если вы инициализируете SDK еще до того
// как получили ID авторизованного пользователя (например в AppDelegate), то удалите строку
// ниже и следуйте нашим рекомендациям из секции 'User (UID)'.
TechAdvertising.shared.uid = "YOUR_AUTHORIZED_USER_ID"

TechAdvertising.initialize(options: TechAdvertisingOptions)

public struct TechAdvertisingOptions {
    public init(
        sessionId: String,
        storeUrl: String,
        transactionProtocol: TransactionProtocol = .CUSTOM,
        initConfig: InitConfig? = nil,
        remoteConfigUrl: String? = nil,
        debugMode: Bool = false,
        httpHeaders: [String: String] = [:]
    )
}

public class TechAdvertising {
    public var uid: String?
}

• sessionId - Уникальный идентификатор сессии, который определяет текущую сессию приложения. Мобильное приложение можно отнести к одному из след. типов:

  • Online приложение (ваше приложение использует ваш backend, серверную часть для хранения и доступа к данным) - в этом случае, в качестве значения, используйте ID сессии, которая соответствует сессии на стороне вашей серверной части - это наиболее предпочтительный вариант значения.
  • Offline приложение (ваше приложение не использует ваш собственный backend, все бизнес данные хранятся локально). В этом случае у вас нет никакой сессии на серверной стороне. При таком сценарии, можно использовать сгенерированный UUID в качестве значения. ВАЖНО: UUID значение должно генерироваться один раз на моменте старта приложения и не меняться пока приложение остается в памяти. Вы не должны перегенерировать UUID в течении жизненного цикла приложения. Новое значение допустимо только, после удаления вашего приложения из памяти, после нового рестарта приложения.

• storeUrl - ссылка на приложение в магазине приложений. Пример: https://apps.apple.com/us/app/myapp/id12345678.

• transactionProtocol - Транзакционный протокол для получения рекламы (со специфичными инициализационными опциями внутри). Это свойство определяет "Layer-3 Transaction", согласно AdCOM v1.0. SDK поддерживает следующие протоколы:

  • CUSTOM - внутренний 'CUSTOM' протокол (используется по умолчанию).
  • OPEN_RTB - OpenRTB 2.6

    OPEN_RTB(
        publisherId: String? = nil,
        appContentType: RTBContext? = nil,
        appContentProductionQuality: RTBProductionQuality? = nil,
        appContentMediaRating: RTBMediaRating? = nil
    )

    • publisherId - (необязательный) Уникальный идентификатор "издателя".
    • appContentType - (необязательный) Описание контента, который предоставляет ваше приложение (game, video, text, и т.п.). См. List: Content Contexts в AdCOM 1.0.
    • appContentProductionQuality - (необязательный) Качественная характеристика вашего приложения как продукта. См. List: Production Qualities в AdCOM 1.0.
    • appContentMediaRating - (необязательный) Медиа рейтинг согласно IQG. См. List: Media Ratings в AdCOM 1.0.

• initConfig - (необязательный) InitConfig объект, который может использоваться вместо remoteConfigUrl параметра (см ниже), для инициализации SDK с URL параметрами вниутри вашего кода: Если вы используете оба InitConfig и remoteConfigUrl параметра, имейте ввиду, что InitConfig будет всегда иметь больший приоритет. Это значит, что все значения из вашего InitConfig объекта перезапишут значения, из такого-же объекта полученного с сервера от remoteConfigUrl ендпоинта.

• remoteConfigUrl - (необязательный) Endpoint URL для получения InitConfig объекта хранимого на сервере. Применяется, когда вы храните и управляете настройками вашего приложения на сервере (RemoteConfig). Пример API ответа в JSON формате:

  JSON

  {
    "core": {
      "bannerUrl": "https://my.server.com/banner_creative",
      "productUrl": "https://my.server.com/product_creative"
    }
  }

• debugMode - флаг, включающий запись в debug сообщения в log приложения. По умолчанию false.

• httpHeaders - словарь при помощи которого формируются специфичные заголовки для HTTP запросов. По умолчанию [:].

• TechAdvertising.shared.uid - (необязательный) - см наши рекоммендации (когда выставлять и когда очищать это значение) в секции User ID (UID).

GEO локация ​

SDK использует текущую GEO локацию устройства, для улучшения механизмов таргетирования баннерной рекламы. Это значит, что вам (как разработчику), необходимо добавить следующие Privacy свойства в вашем Info.plist файле:

• NSLocationWhenInUseUsageDescription="Здесь, вы пишите уведомление для пользователя, где объясняете причину почему ваше приложение использует GEO локацию"
• NSLocationUsageDescription="Здесь, вы пишите уведомление для пользователя, где объясняете причину почему ваше приложение использует GEO локацию"
• NSLocationAlwaysUsageDescription="Здесь, вы пишите уведомление для пользователя, где объясняете причину почему ваше приложение использует GEO локацию"
• NSLocationAlwaysAndWhenInUseUsageDescription="Здесь, вы пишите уведомление для пользователя, где объясняете причину почему ваше приложение использует GEO локацию"
• NSLocationTemporaryUsageDescriptionDictionary="Здесь, вы пишите уведомление для пользователя, где объясняете причину почему ваше приложение использует GEO локацию"

User ID (UID) ​

Ваше мобильное приложение может быть:

• Anonymous (публичное - не требующее для доступа к функционалу авторизации пользователя). Например: любой пользователь, установивший приложение может воспользоваться всем функционалом, без необходимости регистрировать и аккаунт и без необходимости проходить авторизацию для доступа ко всему функционалу вашего приложения.
• AuthN/AuthZ (пользователь должен иметь аккаунт и пройти авторизацию для доступа к функционалу). Например: При старте приложения, пользователь видит 'Sign-in' форму в которой вводит свой логин / пароль. Пока не пройдет авторизацию, пользователь не может зайти на другие экраны.
• Комбинированное приложение (часть экранов/функционала доступна пользователю без авторизации, когда как другая часть только после прохождения таковой). Например: Любой не авторизованный пользователь может просматривать каталог продукции, переходить между карточками товаров. Но в случае, если он хочет оформить заказ, то приложение просит пройти авторизацию (Sign-in / Sign-up формы) - и только после этого пользователь сможет заказать товар.

Ниже приведен примеры кода в какие моменты и какое значение нужно устанавливать внутри TechAdvertising.shared.uid свойства:

myAuthService.signIn(username, password) { authSession, error in
    defer {
        TechAdvertising.shared.uid = authSession.success ? authSession.user.id : nil
    }

    if let error = error {
        print("ERROR: Unable to sign-in due error: \(error.localizedDescription)")
        return
    }

    // Здесь вы выполняете бизнес логику, специфичную для вашего приложения, когда пользователь
    // успешно прошел авторизацию.
    // Например: Переход на 'Главный' экран, или навигация в 'Корзину' для оформления заказа и т.п.
}

public class TechAdvertising {
    public var uid: String?
}

• uid - (необязательный) Уникальный идентификатор пользователя, прошедшего успешную авторизацию внутри вашего приложения.

Показ баннерной рекламы ​

SDK предоставляет функционал по отображению, следующих видов рекламного контента в виде баннеров:

HTML Banner

Рекламный креатив, использующий для отображения рекламы в своей основе HTML контент. Для показа данного типа креатива в SDK используются браузерные механизмы рендеринга HTML (WebKit > WKWebView). Такая реализация подразумевает, что внутрь CreativeView иерархии добавляется HTML страница, которая и представляет собой рекламный контент. Например, в качестве баннера вы можете отобразить форму-опросник для пользователей, которая будет иметь элементы управления, визуальные эффекты и дополнительную логику, выполняемую посредством JavaScript.

Image Banner

Рекламный креатив, использующий для отображения рекламы ссылку на картинку. Является легковестной версией баннера для отображения рекламного контента в виде простой картинки, что влечет большую производительность при показе рекламы и меньшие задержки на рендеринг контента.

Media Banner (video, audio)

Для отображения медиа (видео, аудио) рекламного контента в вашем приложении. Данный типа креатива базируется на VAST спецификации.

Выполните следующие шаги для загрузки и отображения рекламного контента баннера:

1. Добавьте CreativeView в ваш UI layout, представляющий экран приложения, отдельную view, форму и т.п.:

- Добавьте `CreativeView` внутри вашего storyboard(xib), описывающего ваш экран приложения (view).

- Соедините `creativeView` с соответствующим `@IBOutlet` полем вашего view котроллера

- Добавьте `creative` поле внутри вашего view контроллера, например:

  class MyViewController: UIViewController {
      @IBOutlet weak var creativeView: CreativeView!

      private var creative: Creative!
  }

class MyViewController: UIViewController {
    private var creative: Creative!

    override func viewDidLoad() {
        super.viewDidLoad()

        // Создадим и добавим creative view к нашему layout.
        //
        // Вы также можете импользовать CreativeView(frame: CGRect) конструктор, если хотите явно указать
        // размер и позицию вашего баннера на экране.
        // let creativeView = CreativeView(frame: CGRect(x: 0, y: 0, width: 640, height: 480))
        let creativeView = CreativeView()
        superview.addSubview(creativeView)
        creativeView.translatesAutoresizingMaskIntoConstraints = false

        // Здесь, мы назначим constraints для creativeView внутри вашего layout.
        . . .

        // Опционально, вы можете отключить адаптивный UI баннера, используя след. свойства.
        creativeView.isScrollEnabled = true // По умолчанию 'false'
        creativeView.scaleToFit = false     // По умолчанию 'true'
    }
}

2. Зададим параметры запроса для CreativeView, используя CreativeQuery:

class MyViewController: UIViewController {

    @IBOutlet weak var creativeView: CreativeView!

    private var creative: Creative!

    override func viewDidLoad() {
        super.viewDidLoad()

        . . .

        // В случае использования 'CUSTOM' протокола, используйте следующий пример запроса
        creativeView.query = CreativeQuery(
            // ВНИМАНИЕ: Placement ID обязателен при инициализации 'CUSTOM' протокола
            placementId: "YOUR_PLACEMENT_ID",
            sizes: [SizeEntity(width: 260, height: 106)],
            floorPrice: 2.0,
            currency: "RUB",
            customParams: [
              "property1": "value1",
              "property2": "value2"
            ]
        )
        
        // В случае 'OpenRTB', используйте этот пример
        creativeView.query = CreativeQuery(
            // ВНИМАНИЕ: `placementId` не нужен при использовании 'OpenRTB' протокола.
            sizes: [SizeEntity(width: 260, height: 106)],
            
            // ВНИМАНИЕ: `markupType` рекомедован в случае 'OpenRTB' протокола.
            // Установите одно из значений `.BANNER`, `.VIDEO`, `.AUDIO` or `.NATIVE` в вашем запросе.
            markupType: .BANNER,
            
            floorPrice: 2.0,
            currency: "RUB",
            customParams: [
              "property1": "value1",
              "property2": "value2"
            ]
        )
    }
}

3. Создадим Creative контроллер для управления и загрузки баннера.

class MyViewController: UIViewController {

    @IBOutlet weak var creativeView: CreativeView!

    private var creative: Creative!

    override func viewDidLoad() {
        super.viewDidLoad()

        . . .

        // Инициализация Creative
        self.creative = .init(creativeViews: [creativeView])
        self.creative.delegate = self
    }
}

4. Вызовите метод load() у созданного экземпляра Creative

class MyViewController: UIViewController {

    @IBOutlet weak var creativeView: CreativeView!

    private var creative: Creative!

    override func viewDidLoad() {
        super.viewDidLoad()

        . . .

        // Произведем загрузку баннера
        self.creative.load()
    }
}

5. Для обратной связи (о ходе загрузки и работы баннера), используйте CreativeDelegate протокол.

class MyViewController: UIViewController {

    @IBOutlet weak var creativeView: CreativeView!

    private var creative: Creative!

    override func viewDidLoad() {
        super.viewDidLoad()

        . . .

        // Укажем, что view  контроллер будет принимать callback вызовы от Creative контроллера
        self.creative.delegate = self
    }
}

extension MyViewController: CreativeDelegate {

    public func onLoadDataSuccess(creativeView: CreativeView) {
        let placementId = creativeView.query?.placementId
        print("Creative.onLoadDataSuccess[\(String(describing: placementId))]")
    }

    public func onLoadDataFail(creativeView: CreativeView, error: Error) {
        let placementId = creativeView.query?.placementId
        print("Creative.onLoadDataFail[\(String(describing: placementId))]: \(error.localizedDescription)")
    }

    public func onLoadContentSuccess(creativeView: CreativeView) {
        let placementId = creativeView.query?.placementId
        print("Creative.onLoadContentSuccess[\(String(describing: placementId))]")
    }

    public func onLoadContentFail(creativeView: CreativeView, error: Error) {
        let placementId = creativeView.query?.placementId
        print("Creative.onLoadContentFail[\(String(describing: placementId))]: \(error.localizedDescription)")
    }

    public func onNoAdContent(creativeView: CreativeView) {
        let placementId = creativeView.query?.placementId
        print("Creative.onNoAdContent[\(String(describing: placementId))]")
    }

    public func onClose(creativeView: CreativeView) {
        let placementId = creativeView.query?.placementId
        print("Creative.onClose[\(String(describing: placementId))]")
    }
}

Показ динамических списков ​

Если вы планируете использовать динамические списки баннеров внутри вашего приложения, на базе UICollectionViewController, UICollectionViewCell и dequeueReusableCell, мы настоятельно рекомендуем использовать следующий подготовленный пример кода в качестве шаблона: SingleCollectionCreativeViewController.swift

Это позволит вам:

• Упразднить преждевременную загрузку баннеров, до которых пользователь еще не промотал.
• Добиться плавности прокрутки таких списков.
• Минимизировать риски утечки памяти.

Показ товарных креативов ​

Товарный баннер - специальный тип рекламного креатива для RetailMedia платформ, использующий в своей основе SKU идентификатор товара в RetailMedia платформе. SDK на своей стороне в данном случае не производит рендеринг рекламного контента и выполнение функционала трекинга и переходов на посадочную страницу. В данном типе креатива это зона отвественности разработчика. Получив ответ от SDK со списком креативов и их SKU, разработчик формирует отображение рекламного контент на основе уже существующих картинок товаров в платформе по этим SKU, в соответствии с внутренними шаблонам и стилями, обеспечивая вызов необходимых трекинг событий.

class MyViewController: UIViewController {

    private var productCreative: ProductCreative!

    override func viewDidLoad() {
        super.viewDidLoad()
        . . .
        // Let's setup product creative
        self.productCreative = ProductCreative(query: ProductCreativeQuery(
            placementId: "YOUR_PLACEMENT_ID",
            customParams: [
              "property1": "value1",
              "property2": "value2"
            ]
        ))
        self.productCreative.delegate = self
    }

    @IBAction func onRequestButtonClick(_ sender: Any) {
        self.productCreative.load()
    }
}

extension MyViewController: ProductCreativeDelegate {

    public func onNoAdContent(query: ProductCreativeQuery) {
        let placementId = query.placementId
        print("Product.onNoAdContent[\(String(describing: placementId))]")
    }

    func onLoadDataSuccess() {
        print("Product.onLoadDataSuccess")
    }

    func onLoadDataFail(error: Error) {
        print("Product.onLoadDataFail: \(error.localizedDescription)")
    }

    func onLoadContentSuccess(entity: ProductCreativeEntity) {
        print("Product.onLoadContentSuccess: \(String(describing: entity))")
    }

    func onLoadContentFail(query: ProductCreativeQuery, error: Error) {
        print("Product.onLoadContentFail[\(query.placementId)]: \(error.localizedDescription)")
    }
}

• См. ProductCreative
• См. ProductCreativeQuery
• См. ProductCreativeDelegate

Вспомогательные классы ​

InitConfig ​

Объект для инициализации SDK. Содержит в себе url-ы endpoint-ов, для получения различных видов рекламных креативов.

public struct InitConfig {
    public init(core: InitConfigCoreEntity? = nil)
}

• core - (необязательный) Core параметры для инициализации SDK. URl-ы для получения основных типов рекламных креативов (см InitConfigCoreEntity)

InitConfigCoreEntity ​

URl-config for common ad creatives

public struct InitConfigCoreEntity {
    public init(
        bannerUrl: String? = nil,
        productUrl: String? = nil
    )
}

• bannerUrl - (необязательный) URL для получения баннерного креатива.
• productUrl - (необязательный) URL для получения товарного креатива

CreativeView ​

View контейнер, используемый для отображения баннерной рекламы внутри (HTML Banner, Image Banner, Media Banner). Вся внутренняя UI иерархия создается автоматически, базируясь на типе рекламного креатива, полученного в ответе от сервера.

public class CreativeView: UIView {
    public var query: CreativeQuery?
    public var scaleToFit: Bool = true
    public var isScrollEnabled: Bool = false

    public override init(frame: CGRect)
    public required init?(coder: NSCoder)
}

• isScrollEnabled - включает или отключает возможность вертикального и горизонтального. По умолчанию false. скролинга HTML контента внутри фрэйма CreativeView. Например: если вы используете интерактивную форму в виде HTML контента, но вразмер баннера внутри вашего мобильного приложения имеет меньший размер для отображения всего HTML. В этом случае, вы можете включить данную опцию, для предоставления пользователю возможности прокручивать весь контент. внутри CreativeView фрэйма.

  NOTICE

  isScrollEnabled свойство имеет эффект только для HTML баннера.

• scaleToFit - данная опция подстраивает размер полученного баннера к aspect ratio фрэйма, который установлен у CreativeView. По умолчанию true.

• query - (необязательный) - Критерий запроса на получение баннерной рекламы. Усановите этот критерий до вызова функции загрузки. Если вы оставите значение как nil то Creative контроллер будет игнорировать эту view в процессе загрузки. Подробнее см. CreativeQuery

Creative ​

Контроллер для управления баннерными креативами.

public class Creative {

    public weak var delegate: CreativeDelegate?

    public convenience init(creativeView: CreativeView)

    public init(creativeViews: [CreativeView])

    public func load(path: String = "")
}

• init(creativeView: CreativeView) - конструктор контроллера, управляющего одним UI компонентом: CreativeView.
• init(creativeViews: [CreativeView]) - (multiple impressions) конструктор контроллера, управляющего коллекцией UI компонентов: CreativeView.
  • creativeView - CreativeView UI контейнер, используется для отображения рекламного контента, полученного от сервера.
  • creativeViews - коллекция CreativeView UI компонентов.
• delegate - (необязательный) CreativeDelegate callback обработчик событий процесса загрузки и жизненного цикла работы баннера(ов).
• load() - метод для запуска загрузки (и дальнейшего показа) баннера(ов), которыми проинициализирован контроллер.
  • path - путь, который будет добавлен к endpoint URL, откуда запрашиваются баннеры. По умолчанию "".

FullscreenCreativeViewController ​

Контроллер, предназначенный для отображения баннерной рекламы в модальном fullscreen режиме.

class SingleFullscreenCreativeViewController: UIViewController {

    private var fullscreenVC: FullscreenCreativeViewController!
    
    override func viewDidLoad() {
        let vc = FullscreenCreativeViewController()
        vc.delegate = self
        self.fullscreenVC = vc
    }
    
    @IBAction func onButtonClick(_ sender: Any) {
        self.fullscreenVC.query = CreativeQuery(
            placementId: "YOUR_PLACEMENT_ID",
            sizes: [SizeEntity(width: 260, height: 106)],
            customParams: [
              "property1": "value1",
              "property2": "value2"
            ]
        )
        self.present(fullscreenVC, animated: true)
    }
}

// MARK: - CreativeDelegate

extension SingleFullscreenCreativeViewController: CreativeDelegate {

    public func onLoadDataSuccess(creativeView: CreativeView) {
        let placementId = creativeView.query?.placementId
        print("onLoadDataSuccess[\(placementId ?? "")]")
    }

    public func onLoadDataFail(creativeView: CreativeView, error: Error) {
        let placementId = creativeView.query?.placementId
        print("onLoadDataFail[\(placementId ?? "")]: \(error.localizedDescription)")
    }

    public func onLoadContentSuccess(creativeView: CreativeView) {
        let placementId = creativeView.query?.placementId
        print("onLoadContentSuccess[\(placementId ?? "")]")
    }

    public func onLoadContentFail(creativeView: CreativeView, error: Error) {
        let placementId = creativeView.query?.placementId
        print("onLoadContentFail[\(placementId ?? "")]: \(error.localizedDescription)")

        fullscreenVC.dismiss(animated: true)
    }

    public func onNoAdContent(creativeView: CreativeView) {
        let placementId = creativeView.query?.placementId
        print("onNoAdContent[\(placementId ?? "")]")

        fullscreenVC.dismiss(animated: true)
    }

    public func onClose(creativeView: CreativeView) {
        let placementId = creativeView.query?.placementId
        print("onClose[\(placementId ?? "")]")

        fullscreenVC.dismiss(animated: true)
    }
}

public class FullscreenCreativeViewController: UIViewController {

    public var query: CreativeQuery?

    public var path = ""

    public weak var delegate: CreativeDelegate?
    
    public init()
    
    public required init?(coder: NSCoder)

• init(), init?(coder: NSCoder) - стандартные конструкторы, наследуемые из UIViewController.
• query - (необязательный) - Критерий запроса на получение баннерной рекламы. Усановите этот критерий до вызова функции загрузки. Если вы оставите значение как nil то Creative контроллер будет игнорировать эту view в процессе загрузки. Подробнее см. CreativeQuery
• delegate - (необязательный) CreativeDelegate callback обработчик событий процесса загрузки и жизненного цикла работы баннера(ов).
• path - путь, который будет добавлен к endpoint URL, откуда запрашиваются баннеры. По умолчанию "".

CreativeDelegate ​

Обработка событий показа рекламного баннера происходит через обработчик протокола CreativeDelegate.

@objc public protocol CreativeDelegate: AnyObject {
    @objc optional func onLoadDataSuccess(creativeView: CreativeView)
    @objc optional func onLoadDataFail(creativeView: CreativeView, error: Error)

    @objc optional func onLoadContentSuccess(creativeView: CreativeView)
    @objc optional func onLoadContentFail(creativeView: CreativeView, error: Error)

    @objc optional func onNoAdContent(creativeView: CreativeView)

    @objc optional func onClose(creativeView: CreativeView)
}

• onLoadDataSuccess - (необязательный) запрос к рекламному серверу прошел успешно, начали загружать контент креатива;
• onLoadDataFail - (необязательный) ошибка при запросе к рекламному серверу;
• onLoadContentSuccess - (необязательный) креатив успешно загружен;
• onLoadContentFail - (необязательный) ошибка при загрузке креатива;
• onNoAdContent - (необязательный) сервер вернул 204 HTTP код на ваш запрос;
• onClose - (необязательный) пользователь закрыл view просмотра рекламы.

CreativeQuery ​

Критерий для запроса баннерного креатива.

public struct CreativeQuery {
    public var placementId: String
    public var sizes: [SizeEntity]
    public var markupType: MarkupType?
    public var floorPrice: Double?
    public var currency: String?
    public var customParams: [String: String]

    public init(
        placementId: String = "",
        sizes: [SizeEntity],
        markupType: MarkupType? = nil
        floorPrice: Double? = nil,
        currency: String? = nil,
        customParams: [String: String] = [:]
    )
}

• placementId - идентификатор рекламного места. Установите это поле в вашем запросе, если используется 'CUSTOM' протокол SDK. Пример: 123456. Пропустите (не устанавливайте), в случае 'OpenRTB' протокола.

• sizes - список допустимых размеров для баннера. По умолчанию []. Пример: [SizeEntity(width: 260, height: 106)].

• markupType - (необязательный) Тип рекламного креатива (.BANNER, .VIDEO, .AUDIO, .NATIVE). Рекомендованно, если вы используете 'OpenRTB' протокол. Здесь вы определяете какой тип креатива вы ожидаете получить от сервера.

• floorPrice - (необязательный) минимальная цена показа.

• currency - (необязательный) валюта.

• customParams - дополнительные параметры, которые можно передать в запросе на загрузку рекламного контента. По умолчанию [:]. ВНИМАНИЕ: Должен быть передан JSON-совместимый объект, иначе произойдет ошибка (onLoadDataFail()). Например:

  Swift

  customParams: [
    "sku": [
      "id": "LG00001",
      "name": "Lego bricks (speed boat)",
      "extra": [
        "variances": ["Medium", "Electrical"],
        "points": 33.20
      ]
    ],
    "categories": ["Kids", "SpecialOffer", "2025"],
    "gdprConsent": "CPsmEWIPsmEWIABAMBFRACBsABEAAAAgEIYgACJAAYiAAA.QRXwAgAAgivA",
    "ccpa": "1YNN",
    "coppa": 1,
    "discount": 0.20,
    "contacts": [
      [
        "name" to "John Doe",
        "email" to "john.doe@mail.me"
      ],
      [
        "name" to "Jane Groovy",
        "email" to "jane.groovy@mail.me"
      ],
    ]
  ]

Size ​

Объект, описывающий размер места размещения. При инициализации принимает два целых числа соответствующих ширине и высоте места размещения в пикселях.

SizeEntity(width: 300, height: 250)

public struct SizeEntity {
    public let width: Int
    public let height: Int
}

• width - Ширина в пикселях. Пример: 300
• height - Высота в пикселях. Пример: 250

ProductCreative ​

Controller to load (to manage) product creatives.

public class ProductCreative {

    public weak var delegate: ProductCreativeDelegate?

    public convenience init(query: ProductCreativeQuery)

    public init(queries: [ProductCreativeQuery])

    public func load(path: String = "")
}

• init(query: ProductCreativeQuery) - конструктор контроллера, управляющего одним продуктовым креативом. См. ProductCreativeQuery.
• init(queries: [ProductCreativeQuery]) - (multiple impressions) конструктор контроллера, управляющего коллекцией продуктовых креативов. См. ProductCreativeQuery.
• delegate - (необязательный) ProductCreativeDelegate callback обработчик событий процесса загрузки и работы продукт(ов).
• load() - метод для запуска загрузки (и дальнейшего показа) продукта(ов), запросами которых проинициализирован контроллер.
  • path - путь, который будет добавлен к endpoint URL, откуда запрашиваются продуктовые креативы. По умолчанию "".

ProductCreativeQuery ​

Критерий для запроса продуктового креатива.

public struct ProductCreativeQuery {
    public var placementId: String
    public var customParams: [String: String]

    public init(placementId: String, customParams: [String: String] = [:]) {
        self.placementId = placementId
        self.customParams = customParams
    }
}

• placementId - идентификатор рекламного места.

• customParams - дополнительные параметры, которые можно передать в запросе на получение рекламного контента. По умолчанию [:]. ВНИМАНИЕ: Должен быть передан JSON-совместимый объект, иначе произойдет ошибка (onLoadDataFail()). Например:

  Swift

  customParams: [
    "sku": [
      "id": "LG00001",
      "name": "Lego bricks (speed boat)",
      "extra": [
        "variances": ["Medium", "Electrical"],
        "points": 33.20
      ]
    ],
    "categories": ["Kids", "SpecialOffer", "2025"],
    "gdprConsent": "CPsmEWIPsmEWIABAMBFRACBsABEAAAAgEIYgACJAAYiAAA.QRXwAgAAgivA",
    "ccpa": "1YNN",
    "coppa": 1,
    "discount": 0.20,
    "contacts": [
      [
        "name" to "John Doe",
        "email" to "john.doe@mail.me"
      ],
      [
        "name" to "Jane Groovy",
        "email" to "jane.groovy@mail.me"
      ],
    ]
  ]

ProductCreativeDelegate (#product_creative_delegate) ​

public protocol ProductCreativeDelegate: AnyObject {
    func onLoadDataSuccess()
    func onLoadDataFail(error: Error)
    func onLoadContentSuccess(entity: ProductCreativeEntity)
    func onLoadContentFail(query: ProductCreativeQuery, error: Error)
    func onNoAdContent(query: ProductCreativeQuery)
}

• onLoadDataSuccess - запрос к рекламному серверу прошел успешно, начали загружать контент креатива;
• onLoadDataFail - ошибка при запросе к рекламному серверу;
• onLoadContentSuccess - креатив успешно загружен; См. ProductCreativeEntity;
• onLoadContentFail - ошибка при загрузке креатива; См. ProductCreativeQuery;
• onNoAdContent - сервер вернул 204 HTTP код на ваш запрос;

ProductCreativeEntity ​

public struct ProductCreativeEntity {
    public let requestId: String
    public let placementId: String
    public var sku: String
    public var disclaimer: String?
    public var externalId: String
    public var tracking: ProductCreativeTrackingEntity?
    public var advertiser: String?
}

• requestId - id запроса
• placementId - идентификатор рекламного места.
• sku - уникальный идентификатор товара
• disclaimer - (необязательный) письменный отказ от ответственности либо об ограничении ответственности при публикации рекламного контента
• externalId - уникальный внешний идентификатор рекламного объявления
• tracking - (необязательный) объект, содержащий URLs для трекинга событий ProductCreativeTrackingEntity
• advertiser - (необязательный) рекламодатель, который предоставляет креатив

ProductCreativeTrackingEntity ​

Объект, включающий в себя списки tracking urls, которые необходимо вызвать в вашем коде, для соответствующих событий.

public struct ProductCreativeTrackingEntity {
    public var impression: [String] = []
    public var click: [String] = []
    public var view: [String] = []
}

• click - список URLs для трекинга событий клика. По умолчанию [].
• impression - список URLs для трекинга событий показа. По умолчанию [].
• view - список URLs для трекинга событий показа в области видимости. По умолчанию [].