BuzzSDK_Docs

BuzzSDK Documentation for IOS

1. Getting Started
2. BuzzSDK Class Reference
3. BuzzSDKDelegate Protocol

Getting Started

Add the SDK to your project

Cocoa Pods

1. To integrate BuzzSDK for iOS into your Xcode project using CocoaPods, specify it in your Podfile:

    source 'https://github.com/CocoaPods/Specs.git'
    platform :ios, '11.0'
    use_frameworks!
   
    target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
      pod 'BuzzSDK', '3.3.7'
    end
   

2. Then, run the following command:

    $ pod install
   

Manually

1. Drag BuzzSDK.framework to the Embedded Binaries section in the General tap of your project’s main target. Check Copy items if needed and choose to Create groups.

   

2. Add a new Run Script Phase in your target’s Build Phases. IMPORTANT: Make sure this Run Script Phase is below the Embed Frameworks build phase. You can drag and drop build phases to rearrange them. Paste the following line in this Run Script Phase’s script text field:

    bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/BuzzSDK.framework/ios-strip-frameworks.sh" BuzzSDK
   

   

3. (Ignore if your project is a Swift only project) - Set the Always Embed Swift Standard Libraries setting in your targets Build Settings to YES

   

Quick Launch

1. Open your AppDelegate.m file and import the BuzzSDK

    // Objective-C
    #import <BuzzSDK/BuzzSDK.h>
   

    // Swift
    import BuzzSDK
   

2. Copy the lines below and paste them into your AppDelegate’s application:didFinishLaunchingWithOptions:launchOptions method

    // Objective-C
    [BuzzSDK startWithAPIKey: @"YOUR_API_KEY" secretKey: @"YOUR_SECRET_KEY"];
   

    // Swift
    BuzzSDK.startWithAPIKey("YOUR_API_KEY", secretKey: "YOUR_SECRET_KEY")
   

3. Call presentDeck class method to display the SDK UI when appropriate. Typically on your applicationDidBecomeActive app delegate method call. ```smalltalk // Objective-C
   • (void)applicationDidBecomeActive:(UIApplication *)application { [BuzzSDK presentDeck]; }

      ```swift
      // Swift
      func applicationDidBecomeActive(_ application: UIApplication) {
       BuzzSDK.presentDeck()
      }
     

Try it out

You can implement the SDK and try it out with our generic test credentials. Just copy the snippet below as your initialisation call and you could see it on action.

// Objective-C
[BuzzSDK startWithAPIKey: @"e78grdmnqainn9pnz6fllabyzjxptpdq" secretKey: @"0pwb6ep3em0t3dsamr0wqn1lin3h9tir"];

// Swift
BuzzSDK.startWithAPIKey("e78grdmnqainn9pnz6fllabyzjxptpdq", secretKey: "0pwb6ep3em0t3dsamr0wqn1lin3h9tir")

Please contact us to get the BuzzSDK files if you are not using CocoaPods

Setup with Delegate

In most cases you would like to receive notifications from BuzzSDK for specific important events. For this reasons, the BuzzSDK class can have a delegate that must adopt the BuzzSDKDelegate protocol.

To setup a delegate call the setDelegate: class method of the BuzzSDK class after your call to start. For example:

// Objective-C
[BuzzSDK startWithAPIKey: @"YOUR_API_KEY" secretKey: @"YOUR_SECRET_KEY" andSDKOptions:nil];
[BuzzSDK setDelegate:self];

// Swift
BuzzSDK.startWithAPIKey("YOUR_API_KEY", secretKey: "YOUR_SECRET_KEY", andSDKOptions: nil)
BuzzSDK.setDelegate(self)

Setup with Groups

Groups allow you to split users into several groups with different sets of online configuration settings. Groups and online configuration settings are managed via BuzzSDK dashboard (please contact us for access to the dashboard).

When using groups you must initialise the BuzzSDK by calling the startWithAPIKey:secretKey:groupId:andSDKOptions: class method. For example:

// Objective-C
[BuzzSDK startWithAPIKey: @"YOUR_API_KEY" secretKey: @"YOUR_SECRET_KEY" groupId:0 andSDKOptions:nil];

// Swift
BuzzSDK.startWithAPIKey("YOUR_API_KEY", secretKey: "YOUR_SECRET_KEY", groupId: 0, andSDKOptions: nil)

Setup with Remove Ads Alert option

When your account configuration provide Ads, you can setup the BuzzSDK to present a custom alert that allow the user to opt for an Ad free version of the app via payment or subscriptions.

To present such an alert the host app will need to provide the text string for the alert message in the kBUZZSDKOptionRemoveAdsAlertTextKey option when starting the BuzzSDK. If this string is not provided the alert will never be presented. Options are provided as a dictionary when starting the BuzzSDK using the startWithAPIKey:secretKey:andSDKOptions: or startWithAPIKey:secretKey:groupId:andSDKOptions: class methods.

// Objective-C
@interface AppDelegate () <BuzzSDKDelegate>

  ...

NSDictionary *sdkOptions = @{
  // Remove Ads Alerte Text
  kBUZZSDKOptionRemoveAdsAlertTextKey : @"Would you like to stop seeing ads on your app?\nTap OK for premium!",
};

[BuzzSDK startWithAPIKey: @"YOUR_API_KEY" secretKey: @"YOUR_SECRET_KEY" andSDKOptions:sdkOptions];
[BuzzSDK setDelegate:self];

// Swift
class AppDelegate: UIResponder, UIApplicationDelegate, BuzzSDKDelegate

...

let sdkOptions = [
  // Remove Ads Alerte Text
  kBUZZSDKOptionRemoveAdsAlertTextKey : "Would you like to stop seeing ads on your app?\nTap OK for premium!",
]

BuzzSDK.startWithAPIKey("YOUR_API_KEY", secretKey: "YOUR_SECRET_KEY", andSDKOptions: sdkOptions)
BuzzSDK.setDelegate(self)BuzzSDK

If the Remove Ads Alert is presented, the BuzzSDK will call your implementation of BuzzSDKDelegate method buzzSDKRemoveAdsButtonTapped when the user taps on the OK button of the alert view. It is your responsibility to act upon this call and direct the user to the appropriate section on your app where he/she can for instance subscribe to an Ad free version of your app.

// Objective-C
- (void)buzzSDKRemoveAdsButtonTapped {
    // Direct your UI for instance to Subscribe section,
  NSLog(@"Remove Ads button Tapped");
}

// Swift
func buzzSDKRemoveAdsButtonTapped() {
    // Direct your UI for instance to Subscribe section
    print("Remove Ads button Tapped")
}

Advance Configuration Options

BuzzSDK allows you also to define the following options. Just add the key : value pairs to the options dictionary when starting the BuzzSDK using the startWithAPIKey:secretKey:andSDKOptions: or startWithAPIKey:secretKey:groupId:andSDKOptions: class methods.

Resource key	Resource type/values	Description
kBUZZSDKOptionLogLevel	Enum ObjC: Wrapped in NSNumber Swift: Int (Enum raw value) BUZZSDKLogLevelNone BUZZSDKLogLevelError BUZZSDKLogLevelWarning BUZZSDKLogLevelInfo BUZZSDKLogLevelDebug	Define the log level to be used by the SDK in your app.
kBUZZSDKOptionMaxTimeToLiveWhileAppInactiveKey	Int(seconds) ObjC: Wrapped in NSNumber Swift: Int	Indicates maximum amount of time which SDK Deck is allowed to stay present if the app has been made inactive (in seconds). Default value is 600 seconds (10 minutes)
kBUZZSDKOptionNoAdsKey	Bool ObjC: Wrapped in NSNumber Swift: Bool	This option will indicates that the SDK should ignore any Ads provided by the backend config for the SDK session. This will be used when the host app still wants to present the SDK for content but no Ads (i.e. if the user is for example a subscribed user) Default value is false
kBUZZSDKOptionGDPRConsentKey	String ObjC: NSString Swift: String	The Base64-encoded value for the app user’s GDPR consent info as defined here. When provided, the BuzzSDK will report it on tracking pixels and request URI’s macros.

When presenting video content in addition to video ads, the style of the title and kicker of videos while presented in Full Screen or Picture in Picture mode can be configured as options in the same way by passing the key : value pairs below:

Resource key	Resource type/values	Description
kBUZZSDKOptionStyleKickerFontNameKey	String ObjC: NSString Swift: String	The PostScript name of the Font for the kicker of the videos when displayed. See note below regarding custom fonts. Default value is HelveticaNeue-Bold
kBUZZSDKOptionStyleKickerFontSizeInFullscreenKey	Float(Point Size) ObjC: Wrapped in NSNumber Swift: Float	The size in points to apply to the kicker of a video when displayed in Full Screen mode . Default value is 12.0
kBUZZSDKOptionStyleKickerFontSizeInPIPKey	Float(Point Size) ObjC: Wrapped in NSNumber Swift: Float	The size in points to apply to the kicker of a video when displayed in Picture In Picture mode . Default value is 10.0
kBUZZSDKOptionStyleKickerTextColorKey	UIColor	The UIColor instance to use for the video’s kicker text color when displayed. Default value is [UIColor whiteColor]
kBUZZSDKOptionStyleTitleFontNameKey	String ObjC: NSString Swift: String	The PostScript name of the Font for the video’s title when displayed See note below regarding custom fonts. Default value is HelveticaNeue
kBUZZSDKOptionStyleTitleFontSizeInFullscreenKey	Float(Point Size) ObjC: Wrapped in NSNumber Swift: Float	The size in points to apply to the title of a video when displayed in Full Screen mode. Default value is 15.0
kBUZZSDKOptionStyleTitleFontSizeInPIPKey	Float(Point Size) ObjC: Wrapped in NSNumber Swift: Float	The size in points to apply to the title of a video when displayed in Picture In Picture mode. Default value is 12.0
kBUZZSDKOptionStyleTitleTextColorKey	UIColor	The UIColor instance to use for the video’s title text color when displayed. Default value is [UIColor whiteColor]
kBUZZSDKOptionStyleTitleBackgroundColorKey	UIColor	The UIColor instance to use for the text areas background color on both Full Screen and Picture In Picture mode. Default value is UIColor with RGBA 0x0000000A

BuzzSDK Class Reference

startWithAPIKey:secretKey:

Initialises the BuzzSDK. Simplified version of initialisation using default options and default group.

// Objective-C
+ (void)startWithAPIKey:(nonnull NSString *)APIKey secretKey:(nonnull NSString *)secretKey;
}

// Swift
class func start(withApiKey apiKey : String, secretKey : String)

Parameter	Description
apiKey	Please contact us to request your app configuration including the keys
secretKey	Please contact us to request your app configuration including the keys

startWithAPIKey:secretKey:andSDKOptions:

Initialises the BuzzSDK including options and using default group.

// Objective-C
+ (void)startWithAPIKey:(nonnull NSString *)APIKey secretKey:(nonnull NSString *)secretKey andSDKOptions:(nullable NSDictionary *)SDKOptions;

// Swift
class func start(withApiKey apiKey : String, secretKey : String, andOptions SDKOptions [String:AnyHashable]?)

Parameter	Description
apiKey	Please contact us to request your app configuration including the keys
secretKey	Please contact us to request your app configuration including the keys
SDKOptions	See Configuration Options for options description

startWithAPIKey:secretKey:groupId:andSDKOptions:

Initialises BuzzSDK with a group id and options (optional).

// Objective-C
+ (void)startWithAPIKey:(nonnull NSString *)APIKey secretKey:(nonnull NSString *)secretKey groupId:(NSInteger)groupId andSDKOptions:(nullable NSDictionary *)SDKOptions;

// Swift
class func start(withApiKey apiKey : String, secretKey : String, groupId : Int, andOptions SDKOptions [String:AnyHashable]?)

Parameter	Description
apiKey	Please contact us to request your app configuration including the keys
secretKey	Please contact us to request your app configuration including the keys
groupId	Id for group configuration when using the BuzzSDK with Groups. Contact us for details and groups setup.
SDKOptions	See Configuration Options for options description

setDelegate

Sets the delegate object to respond to BuzzSDK call backs.

// Objective-C
+ (void)setDelegate:(nonnull NSObject<BuzzSDKDelegate> *)delegate;

// Swift
class func setDelegate(_ delegate : BuzzSDKDelegate)

See BuzzSDKDelegate

presentDeck

Starts presentation of the BuzzSDK UI on top of the host app’s UI.

// Objective-C
+ (void)presentDeck;

// Swift
class func presentDeck()

Call this method when you want to trigger the presentation of the BuzzSDK UI or to show it again after it has been hidden by calling hideDeck method. It is safe to call this method multiple times, but it only has effect if BuzzSDK UI is not presented yet or hidden.

pause

Instructs the BuzzSDK to pause any video that is currently playing.

// Objective-C
+ (void)pause

// Swift
class func pause()

hideDeck

Will hide the BuzzSDK UI (if presented) from the user. UI can be brought back on top of the host app UI by calling presentDeck again. If the UI is hidden when the app is sent to the background, the BuzzSDK will be dismissed and calling presentDeck will start a new BuzzSDK Session. Similarly, calling hideDeck before the BuzzSDK UI is set (i.e. while on BuzzSDKStateNone or BuzzSDKStatePrepared state) will terminate the BuzzSDK session and calling presentDeck will start a new BuzzSDK Session.

// Objective-C
+ (void)hideDeck;

// Swift
class func hideDeck()

dismissDeck

Will completely stop the BuzzSDK and remove it from the view hierarchy.

// Objective-C
+ (void)dismissDeck;

// Swift
class func dismissDeck()

updateGDPRConsent

Will set or update the GDPR consent string (gdprConsent) to be used by the BuzzSDK when performing Ad request and Ad tracking.

For details on how to generate the BASE64 GDPR Consent string for your users, please refer to IAB’s Transparency & Consent Framework

// Objective-C
+ (void)updateGDPRConsent:(nonnull NSString *)gdprConsent;

// Swift
class func updateGDPRConsent(_ gdprConsent : String)

BuzzSDKDelegate Protocol

BuzzSDKDelegate

The methods declared by the BuzzSDKDelegate protocol allow the adopting delegate to respond to messages from the BuzzSDK class and thus respond to, and in some affect, UI interactions such as tapping on Remove Ads alert OK button, starting video playback, hiding or showing the UI, etc.

Methods

• buzzSDKRemoveAdsButtonTapped
• buzzSDKHasStartedVideoPlayback
• buzzSDKStateHasChanged:

buzzSDKRemoveAdsButtonTapped

// Objective-C
- (void)buzzSDKRemoveAdsButtonTapped;

// Swift
func buzzSDKRemoveAdsButtonTapped()

Discussion

If the Remove Ads Alert is presented, the BuzzSDK will call your implementation of this method when the user taps on the OK button of the alert view. It is your responsibility to act upon this call and direct the user to the appropriate section on your app where he/she can for instance subscribe to an Ad free version of your app.

buzzSDKHasStartedVideoPlayback

// Objective-C
- (void)buzzSDKHasStartedVideoPlayback;

// Swift
func buzzSDKHasStartedVideoPlayback()

Discussion

Notifies the delegate that the BuzzSDK has started playback of video content. This will be notified every time video playback starts on any content element.

buzzSDKStateHasChanged:

// Objective-C
- (void)buzzSDKStateHasChanged:(BuzzSDKState)state

// Swift
func buzzSDKStateHasChanged(_ state: BuzzSDKState)

Discussion

Notifies the delegate of a state change on the BuzzSDK. When started the BussSDK state is always BuzzSDKStateNone.

The states are:

• BuzzSDKStateNone: The BuzzSDK has been initialised, but the configuration not loaded and its UI hierarchy is not set.
• BuzzSDKStatePreparing: The BuzzSDK is fetching configuration from backend in preparation for presentation. This state is triggered after calling presentDeck while in BuzzSDKStateNone state.
• BuzzSDKStatePrepared: The BuzzSDK configuration has been fetched, and content has started to load, the UI Hierarchy is not yet set and no content is currently being presented.
• BuzzSDKStatePresenting: The BuzzSDK UI Hierarchy is set, and content is currently being presented.
• BuzzSDKStateHiddenByHostApp: The BuzzSDK UI Hierarchy is set, content is displayed but currently hidden by host app request. User can not manually show it again but host app can by calling presentDeck class method.
• BuzzSDKStateHiddenByUser: The BuzzSDK UI Hierarchy is set, content is displayed but currently hidden by user request. A Show Videos buttons is displayed so user can show the UI again on request.