Skip to main content

ios

LORA Short Video SDK is a component of the LORA SDK that can be utilized alongside other modules within the LORA SDK or independently. To function properly, the LORA Short Video SDK necessitates the LoraCore module

Features

  • Video Grid View
  • Video Carousel View
  • Video Storyblock View
  • Video Detail Player (with landscape layouto support)
  • Playlist
  • PIP

Requirements

  • iOS 11.0+
  • Xcode 13.0 and above

Integration

Below are the steps to independently add the LORA Short Video SDK to your project.

CocoaPods​

This is the easiest method to integrate the LORA Short Video SDK into your app. You can utilize CocoaPods to install the LORA Short Video SDK by adding it to your Podfile.

platform :ios, '11.0'
use_frameworks!
pod 'LoraCore', :path => '../framework/LoraCore' # path to podspec file
pod 'LoraShortVideo', :path => '../framework/LoraShortVideo' # path to podspec file

Carthage​

LORA Short Video SDK is distributed via xcframework which is recommended by Apple since WWDC 2019

Step 1: Add frameworks​

Drag LoraCore.xcframework and LoraShortVideo.xcframework into Frameworks, Libraries, and Embedded Contents and Select Embedded & Sign

Step 2: Update Cartfile​

You may encounter the build error or get crash: dyld: Symbol not found on Xcode 12 and above when using xcframework . Here is a workaround to fix this issue

  • Create file carthage.sh in your root project folder with this content
# carthage.sh
# Usage example: ./carthage.sh build --platform iOS

set -euo pipefail
 
xcconfig=$(mktemp /tmp/static.xcconfig.XXXXXX)
trap 'rm -f "$xcconfig"' INT TERM HUP EXIT
 
# For Xcode 12 make sure EXCLUDED_ARCHS is set to arm architectures otherwise
# the build will fail on lipo due to duplicate architectures.
 
CURRENT_XCODE_VERSION="$(xcodebuild -version | grep "Xcode" | cut -d' ' -f2 | cut -d'.' -f1)00"
CURRENT_XCODE_BUILD=$(xcodebuild -version | grep "Build version" | cut -d' ' -f3)

echo "EXCLUDED_ARCHS__EFFECTIVE_PLATFORM_SUFFIX_simulator__NATIVE_ARCH_64_BIT_x86_64__XCODE_${CURRENT_XCODE_VERSION}__BUILD_${CURRENT_XCODE_BUILD} = arm64 arm64e armv7 armv7s armv6 armv8" >> $xcconfig
 
echo 'EXCLUDED_ARCHS__EFFECTIVE_PLATFORM_SUFFIX_simulator__NATIVE_ARCH_64_BIT_x86_64__XCODE_'${CURRENT_XCODE_VERSION}' = $(EXCLUDED_ARCHS__EFFECTIVE_PLATFORM_SUFFIX_simulator__NATIVE_ARCH_64_BIT_x86_64__XCODE_$(XCODE_VERSION_MAJOR)__BUILD_$(XCODE_PRODUCT_BUILD_VERSION))' >> $xcconfig
echo 'EXCLUDED_ARCHS = $(inherited) $(EXCLUDED_ARCHS__EFFECTIVE_PLATFORM_SUFFIX_$(EFFECTIVE_PLATFORM_SUFFIX)__NATIVE_ARCH_64_BIT_$(NATIVE_ARCH_64_BIT)__XCODE_$(XCODE_VERSION_MAJOR))' >> $xcconfig

# build all libraries for distribution
# https://github.com/Carthage/Carthage/issues/2845
echo 'BUILD_LIBRARY_FOR_DISTRIBUTION=YES' >> $xcconfig

export XCODE_XCCONFIG_FILE="$xcconfig"
carthage "$@"
  • Add run permission to this file by chmod +x carthage.sh
  • Instead of running carthage command, we'll change to run carthage.sh. Eg: sh carthage.sh update --platform iOS --no-use-binaries --use-xcframeworks

Initialize SDK

Before utilizing its features, it's essential to initialize the LORA SDK. You can initiate the SDK using the provided code along with the licenseKey. To obtain this licenseKey, please reach out to our support team.

import LoraCore

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Initialize LORA SDK
        LoraSDK.shared.initWith(licenseKey)
        .
        .
        .
    return true
    }
}

ShortVideoView

The ShortVideoView serves as an entry point within the UI and is designed to present a variety of video view types: vertical grid, horizontal grid, and carousel. When a user clicks on a video item, it triggers the opening of the primary player, which then plays the selected video. Incorporating a ShortVideoView is as straightforward as adding any other view, and it can be accomplished through either Storyboard or code.

let shortVideoView = ShortVideoView(frame: self.view.bounds)

Upon execution, the ShortVideoView fetches video data from a ShortVideoSource. This source is defined by a ShortVideoConfiguration, which determines the layout type and offers customization options for the UI. Additionally, it manages certain fundamental player behaviors.

Grid Layout​

The grid layout is designed to support a vertical scroll direction. You can set it up like this:

let layout = ShortVideoGridLayout.default
let configuration = ShortVideoConfiguration()
configuration.layout = layout
.
.
.
shortVideoView.configuration = configuration

You have the flexibility to modify the number of columns via the layout configuration:

layout.numberOfColumns = numberOfColums

Various attributes can be customized with the grid layout, including:

  • Background color
  • Spacing between items

Grid Item​

For customization of individual grid items, the LORA Short Video SDK offers the following attributes:

  • Item ratio (width/height)
  • Corner radius
  • Background color
  • Play button (set to nil to hide it)
  • Mute button (set to nil to hide it)
  • Thumbnail scale mode
  • Video scale mode

The carousel layout is designed to support a horizontal scroll direction. You can set it up like this:

let layout = ShortVideoCarouselLayout.default
let configuration = ShortVideoConfiguration()
configuration.layout = layout
.
.
.
shortVideoView.configuration = configuration

With the carousel layout, attributes that can be customized include:

  • Background color
  • Spacing between items
  • Video scale mode

For customization of individual carousel items, the LORA Short Video SDK provides the following attributes:

  • Item ratio (width/height)
  • Corner radius
  • Background color
  • Play button (set to nil to hide it)
  • Mute/unmute button
  • Thumbnail scale mode
  • Video scale mode

Storyblock Layout​

The storyblock layout is designed to support a horizontal scroll direction. 

let layout = ShortVideoStoryBlockLayout.default
let configuration = ShortVideoConfiguration()
configuration.layout = layout
.
.
.
shortVideoView.configuration = configuration

You have the ability to disable scrolling, update item configurations, and customize the next/previous buttons. Here are the attributes that can be customized:

  • Container background color
  • Background color
  • Previous button (set to nil to hide it)
  • Next button (set to nil to hide it)

Storyblock Item​

For customization of individual storyblock items, the LORA Short Video SDK provides the following attributes:

  • Background color
  • Corner radius
  • Title
  • Progress
  • Play/pause button
  • Mute/unmute button
  • Fullscreen button
  • Share button
  • Thumbnail scale mode
  • Video scale mode
  • Product item view

Starting from LORA Short Video SDK 1.1.0, this layout type can display overlay data, including product lists, polls, and Q&A. For more information about overlay data, please refer to the Detail Player below.

Detail Player​

When a video item is clicked, a detailed video screen will open to play the chosen video. You can navigate between items by swipe up and down gesture. This screen supports various features including product view, Q&A, polling, video seeking, and Picture-in-Picture (PIP). The Detail Player is an internal controller, which cannot be modified, but its UI and player behavior can be configured through configuration.detailConfiguration. If you wish to prevent this screen from appearing, set configuration.detailConfiguration = nil. The following attributes within the detailConfiguration can be adjusted:

  • Allow scroll
  • Background color
  • Previous button (set to nil to hide it)
  • Next button (set to nil to hide it)
  • Close button (set to nil to hide it)

Detail Player Item​

For customization of individual items within the detail player, the LORA Short Video SDK provides the following attributes:

  • Background color
  • Corner radius
  • Title
  • Progress seekbar
  • Play/pause button
  • Mute/unmute button
  • PIP button
  • Share button
  • Thumbnail scale mode
  • Video scale mode

Product Item​

A list of products can be linked to a video item and displayed in detail. Each product item can include a Shop CTA (Call to Action) button that opens the product URL in an external browser (this behavior can be overridden). The product item's UI can be customized with attributes such as:

  • Background color
  • Corner radius
  • Title
  • CTA button: Text, Color, Image
  • Thumbnail scale mode

Q&A Item​

A Q&A can be associated with a video item and shown in detail. Each Q&A item contains a CTA (Call to Action) button to submit an answer. The Q&A item's UI can be customized, including:

  • CTA button: Text Color, Background Color

Poll Item​

A Poll can be linked to a video item and displayed in detail. Each Poll item contains a CTA button to submit an answer. The Poll item's UI can be customized, such as:

  • CTA button: Text Color, Background Color

Landscape layout​

By default, the detail player renders the UI according to the orientation of the current user's device. The SDK smoothly transitions between orientation modes, switching from portrait to landscape and vice versa without interrupting the player. However, you can also enforce a fixed orientation (portrait or landscape) using the SDK.

let configuration = ShortVideoConfiguration()
configuration.detailConfiguration?.layout.orientationMode = .landscape

Supported orientation modes

  • auto: Automatically adjust the orientation based on the device's orientation.
  • portrait: Enforce a portrait orientation.
  • landscape: Enforce a landscape orientation.

Picture in Picture (PiP)​

The detail player supports playing a video in Picture in Picture (PiP) mode, there are 2 type of PIPs supported by LORA Short Video SDK:

  • Native PIP (supported by Apple), available on iOS 14 and above
  • Custome PIP, iOS below 14.

You can disable this feature by hiding the PIP button (set it to nil). When a video is playing in this mode, it will always loop regardless of the player completion action.

Player behaviors​

Player behaviors define actions when a video item changes. LORA Short Video SDK supports 2 behaviors autoplay and Player complete action. You can configure these using the configuration.player.autoPlay property and configuration.player.playerCompleteAction property

For playerCompleteAction, you have 4 options: There are 4 options that you can set:

  • Stop: The player will always stop the video after finishing playing it.
  • Loop: The player will always loop the current video.
  • PlayNextItem: The player will always play the next video in the list. If the current video is the last item, the player will stop playing.
  • PlayNextItemAndLoop: The player will always play the next video in the list. If the current video is the last item, the player will play the first item in the list.

ShortVideoSource​

LORA Short Video SDK supports 2 types of video sources:

Playlist​

The playlist video source will fetch all the available videos from a specific playlist by an ID. To create a playlist source, use the below API

ShortVideoSource.init(playlistId: String, maxItemsCount: Int? = nil)

Setting a maxVideoItemsCount greater than 0 will limit the number of videos to load, and set nil to show all videos in the playlist.

Single​

The single video source will fetch a single video by a video id. To create a single source, use the below API

ShortVideoSource.init(videoId: String)

Play & Pause​

User can pause and resume the video by calling the following APIs:

shortVideoView.pause()
//
shortVideoView.play()

Delegates​

LORA Short Video SDK provides various delegates to listen to events when tapping on an item, product CTA, or when errors occur.

public protocol BLShortVideoErrorDelegate: AnyObject {
    /// Callback when any error occur
    /// - Parameters:
    ///   - view: ShortVideoView
    ///   - error: ShortVideoError error
    func shortVideoView(view: ShortVideoView, onError error: ShortVideoError)
}

public protocol BLShortVideoItemDelegate: AnyObject {
    /// Callback when short video item is clicked
    /// - Parameters:
    ///   - view: ShortVideoView
    ///   - videoId: videoId
    func shortVideoView(view: ShortVideoView, itemDidClick videoId: String)
}

public protocol BLShortVideoShareItemDelegate: NSObject {
    /// Callback when share button is clicked
    /// - Parameters:
    ///   - videoId: videoId
    ///   - handle: if handle completion is `true`, nothing happen otherwise it'll show default system share
    func shortVideoItemDidShare(videoId: String, handle: @escaping (Bool) -> Void)
}

public protocol BLShortVideoProductItemCTADelegate: AnyObject {
    /// Callback when product item call to action button is clicked
    /// - Parameter product: product object
    func shortVideoViewProductItemCTADidClick(product: BLShortVideoProduct)
}

public protocol BLShortVideoSubmitPollErrorDelegate: AnyObject {
    /// Callback when any error occur
    /// - Parameters:
    ///   - errorCode: Error code
    func onSubmitPollError(errorCode: Int)
}

public protocol BLShortVideoSubmitQnAErrorDelegate: AnyObject {
    /// Callback when any error occur during submit default answer
    /// - Parameters:
    ///   - errorCode: Error code
    func onSubmitDefaultAnswerError(errorCode: Int)

    /// Callback when any error occur during submit followup answer
    /// - Parameters:
    ///   - errorCode: Error code
    func onSubmitFollowupAnswerError(errorCode: Int)
}