Skip to main content

Banners place

Starting with SDK version 1.26.0, banner display functionality has been added.

Initialization​

To embed the banner widget into your application, you must first initialize the SDK (if it has not been initialized previously with other functionality). SDK initialization is covered in the Basic initialization section.

Banners can be added as StoryView:

var bannersView: IASBannersView!

override func viewDidLoad() {
    super.viewDidLoad()
        
    bannersView = IASBannersView(placeID: <String> = "default", 
                                 appearance: <IASBannersAppearance> = .init(), 
                                 frame: <CGRect> = .zero)
        
    view.addSubview(bannersView)
    
    bannersView.create() // beginning of the widget's internal logic
}

After calling the create() method, the internal logic for opening a session and obtaining a list of banners will start. You can track the loading of banners in the bannersDidUpdated closure (see description below).

Please note

Prior to version 1.28.6, the first call to the create() method cached the data received from the server, and subsequent calls—even for new IASBannersView instances—retrieved data from the cache

Starting with version 1.28.6, the create() method always fetches the banner list from the server unless preload banners place has been called. Read more about preloading here read here

Customization​

To change the appearance of banners, use the IASBannersAppearance object:

struct IASBannersAppearance {
   let shouldLoop: Bool // if banner place is looped, default = true
   let sideInset: CGFloat // which part (in dp) of other banners will be shown with current, default = 0.0
   let leadingInset: CGFloat // setting the cast parameter for indentation (if not specified, it is taken from sideInset)
   let trailingInset: CGFloat // setting the cast parameter for indentation (if not specified, it is taken from sideInset)
   let interItemSpacing: CGFloat // distance (in dp) between banners, default = 8.0
   let cornerRadius: CGFloat // radius (in dp) of banners, default = 16.0
}

This object must be set when initializing the banner widget. Once set, it cannot be changed. If you need to change the appearance of the widget, you must create a new instance of it.

var bannersView: IASBannersView!

override func viewDidLoad() {
    super.viewDidLoad()
    
    let bannersAppearance = IASBannersAppearance(shouldLoop: false,
                                                 sideInset: 24.0,
                                                 interItemSpacing: 16.0,
                                                 cornerRadius: 8.0)
                                                 
    bannersView = IASBannersView(appearance: bannersAppearance)
        
    view.addSubview(bannersView)
    
    bannersView.create()
}

Preloading​

To make Banners place showing faster, you can preload banners data by placeID. Call InAppStory.shared.preloadBanners(placeID: String, complete: @escaping (Result<Bool, Error>) -> Void) and wait for completion.

Pay attention
Preloading is only possible after SDK initialization.

Basic preloading (for example, on a Splash Screen)​

InAppStory.shared.preloadBanners(placeID: <placeID>) { result in
    switch result {
    case .success:
        // Data was loaded
        break
    case .failure:
        // Loading error
        break
    }
}

Please note
After preloading a banner place, all instances of the IASBannersView object with a preloaded placeID will retrieve data only from the cache. To update the data in the list, you must either call the refresh() method or trigger the preload again.

Actions​

To track the actions of the banner widget, you need to subscribe to the closures:

  • bannersDidUpdated: <(_ isContent: <Bool>, _ count: <Int>, _ listHeight: <CGFloat>) -> Void> - called when the banner list is updated, for example, when first loaded, after calling create() or refresh() to update the list:
    • isContent: <Bool> - a parameter showing whether there is content in the widget;
    • count: <Int> - a parameter showing how many items are in the list (can be used for dot control navigation);
    • listHeight: <CGFloat> - the height of the widget relative to its width and the calculated size of the largest banner;
  • onActionWith: (_ target: <String>) -> Void: called when an action occurs inside the banner, such as clicking a button with a link;
    • target: <String> - link obtained as a result of clicking a button in the banner;
  • bannersDidScroll: (_ index: <Int>) -> Void: called when the banner list is scrolled. This can be a swipe through the list, scrolling by an internal timer, or by external methods (described below);
    • index: <Int> - the index to which the banner list has scrolled (can be used for dot control navigation);
extension ViewController {
    func observers() {
        bannersView.bannersDidUpdated = { isContent, count, listHeight in
            // banner list updated
            // skeleton or preloader (if present) can be removed
            // banner container height can be updated using the listHeight parameter
        }
        
        bannersView.onActionWith = { target in
            // an action was performed
            // here you can process the link
            // that came in the target parameter
        }
        
        bannersView.bannersDidScroll = { index in
            // list of banners has been updated
            // dot control navigation can be updated
        }
    }
}

To control the display and movement of banners, you can use methods to flip to the nearest ones or jump to a specific index:

  • showNext() - used to jump to the next banner in the list;
  • showPrevious() - used to go to the previous banner in the list;
  • showBannerWith(index: <Int>) - used to go to a specific banner by index (can be used for dot control navigation);
extension ViewController {
    func nextButtonTouch() {
        bannersView.showNext()
    }
    
    func previosButtonTouch() {
        bannersView.showPrevious()
    }
    
    func dotControlTouch(with index: Int) {
        bannersView.showBannerWith(index: index)
    }
}

Similarly, there are methods for controlling playback in banners that control the internal page-turning timer.

  • pause() - stops the internal timer (the timer will restart upon any user interaction with the banner);
  • resume() - resumes the logic of the internal timers;
extension ViewController {
    func disappearController() {
        bannersView.pause()
    }
    
    func appearController() {
        bannersView.resume()
    }
}

Events​

For banners, a new subobject IASBanner has been added to the IASEvent object (for more details, see the Events section).

  • IASEvent.IASBanner.bannersLoaded(placeID: String? = nil) - the list of banners has loaded, IASBannersView is ready to work (fires every time the list is loaded, and also on refresh).
    • placeID - banners place identifier;
  • IASEvent.IASBanner.show(bannerData: IASBannerData) - called when a banner is displayed on the screen.
    • bannerData - containing a brief description of the selected banner;
  • IASEvent.IASBanner.preloaded(placeID: String, banners: Array<IASBannerData>) - called when a banners is preloaded by place.
    • placeID - banners place identifier;
    • bannerData - containing a brief description of the selected banner;
  • IASEvent.IASBanner.widgetEvent(bannerData: IASBannerData, name: String, data: Dictionary<String, Any>?)
    • bannerData - containing a brief description of the selected banner;
    • name - name of widget;
    • data<Dictionary<String, Any>?> - activated widget data, detailed data fields;