Hippo-iOS-SDK Documentation (China Version)

iOS ad SDK：
hippo-sdk-frameworks-1.3.0.zip

Update Log**：**

provide reward video ads and banner ads APIs | | v1.2.2 | junewong | 2019-05-30 | 1.iOS platform supports click callback；
2.iOS；platform supports loading and showing error callback
3.Interface method for showVideoAd is changed into showRewardVideoAd
4.Minor bug fixes | | v1.2.3 | junewong | 2019-06-06 | 1. Alter and add some event trackers | | v1.2.4 | junewong | 2019-06-06 | 1.Update third-party ad SDK from 1.9.9.2 to 2.0.1.1 | | v1.2.5 | junewong | 2019-06-11 | 1.Optimize isLoaded method | | v1.2.8 | junewong | 2019-06-28 | 1. Add channel parameters supporting config statistics | | v1.2.9 | junewong | 2019-07-01 | 1.Upgrade third-party SDK to 2.0.1.1
2.Add click-to close feature to banner adds | | v1.3.0 | junewong | 2019-07-18 | 1.Upgrade third-party SDK to 2.1.0.2 | | | | | |

I. Introduction

This SDK is applied to accessing the advertisement monetizing platform in China, and ensures high efficiency and low maintenance cost with simple procedures to use the advertisement platform and its integrated analysis tools.

II. Preparation

1. Download the above zip package from HippoSDK

2. Acquire following information from Hippo operational staff：

• Configuration file hippo-ads-config.json. It contains information related to ads, please do not modify；
• Conglomerated ad place ID that will be used to call codes；
• Douyin platform AppId if you want to share to Douyin (need to fill in schema in sharing function)；

III. Procedures

1. Decompress hippo-sdk-frameworks-xxx.zip and import all frameworks；

Among them if screen recording is not needed, lib-recorder is not necessary to be imported, while other libraries are necessary.

1. Import SDK config file

Import hippo-ads-config.json to the root directory of the Project (do not modify the name of .json file)：

hippo-ads-config.json

1. iOS project runtime environment configuration

Supported environment：

• System version: iOS 8.X or later;
• SDK compilation environment Xcode 9.4, Base SDK 11.1;
• Supported architecture: i386, x86-64, armv7, armv7s, arm64 ( above arm64 for real machine)

Please check the following project configuration：

a）Network permission configuration

All existing SDK APIs support HTTPS, but sometimes the main ad element doesn’t. To solve this：

Go to project plist setting, click the ‘+’ next to Information Property List on the right to expand, add information Property List, click arrow on the left to expand, add ‘+’ on the right, auto-fill Allow Arbitrary Loads, and modify its value to YES.

b）Check whether the following libraries exists, add if not：

Project should find Link Binary With Libraries in Allow Arbitrary Loads. Click ‘+’ and add the dependent libraries missing from the following list：

• StoreKit.framework
• MobileCoreServices.framework
• WebKit.framework
• MediaPlayer.framework
• CoreMedia.framework
• AVFoundation.framework
• CoreLocation.framework
• CoreTelephony.framework
• SystemConfiguration.framework
• AdSupport.framework
• CoreMotion.framework
• libresolv.9.tbd
• libc++.tbd
• libz.tbd

c）Add parameter to ‘Other Linker Flags’：

Add parameter -ObjC to Build Settings – Other Linker Flags. SDK supports -all_load at the same time.

1. Config sharing function (optional)

a）In Xcode, choose your project setting, click ‘TARGETS’, add ‘douyinsharesdk’ (for sharing) and ‘douyinopensdk’ (for authorizing signing in) in the ‘“LSApplicationQueriesSchemes’ of ‘info’ tab. Sharing also needs permission to access gallery: add ‘Privacy - Photo Library Usage Description’ in ‘info’ tab.

b）In Xcode, choose the last URL Types from your TARGET – Info and fill in the Appid of Douyin. fill clientkeydouyin in identifier：

IV. Instructions of using SDK

1. Initialize SDK

Initialize SDK at the beginning of the app. SDK will automatically search json configuration file and execute initialization.

// AppDelegate.m
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [HippoAdSDK initSDK];
    return YES;
}

2. Using ad functions

a） Ad request

Use conglomerated ads place ID and request corresponding ad type.
Please be aware that request once is enough. Later every time an ad is shown or loaded with error, it will automatically request next ad to be loaded.

// Reward video ad placement id
static NSString* const kRewardedVideoAdUnitId = @"bfe4445553d1ff53dea7354c516c844e";

// Load ad to specified ad placement (only one call is needed for a placement)
[[HippoAdSDK platformWithAdUnitId:kRewardedVideoAdUnitId] loadRewardedVideoAd];

b）Show ad

Show reward video ads. Call when triggering ads is needed：

// Show reward video ad on specified placement
[[HippoAdSDK platformWithAdUnitId:kRewardedVideoAdUnitId] showRewardedVideoAd];

c) Determine whether ad is loaded

Determine whether specified ad placement is successfully loaded

// Determine whether an ad is loaded
if ( [[HippoAdSDK platformWithAdUnitId:kRewardedVideoAdUnitId] isLoaded] ) {
    // Logic after confirming ad is loaded
}

d）Set ad callback

Prepare callback method in every page to show ads：

// ViewController.m
- (void) viewDidLoad {
    [super viewDidLoad];
    if ( [HippoAdSDK isReady] ) {
        // info is any customized log show method
        [self info:@"SDK is ready."];
        // callback object to realize HPAdPlatformDelegate protocol
        [[HippoAdSDK platformWithAdUnitId:kRewardedVideoAdUnitId] setDelegate:self];

      } else {
        [self info:@"SDK init fail."];
      }
}

Callback method to realize HPAdPlatformDelegate

Among them, asUnitID is ad placement id, adType is defined in HPAdConstant.h ‘Ad Type’.

#pragma mark - AD delegate

// Ad is loaded
- (void)adLoadedWithAdUnitId:(NSString*)adUnitId adType:(NSString*)adType
{
    [self info:[NSString stringWithFormat:@"%@ is loaded, id:%@", adType, adUnitId]];
}

// Ad is closed
- (void)adClosedWithAdUnitId:(NSString*)adUnitId adType:(NSString*)adType
{
    [self info:[NSString stringWithFormat:@"%@ is closed, id:%@", adType, adUnitId]];
}

// Ad reward is issued
- (void)adRewardedWithAdUnitId:(NSString*)adUnitId adType:(NSString*)adType
{
    [self info:[NSString stringWithFormat:@"%@ video is rewared, id:%@", adType, adUnitId]];
}

// Ad is clicked
- (void)adClickedWithAdUnitId:(NSString*)adUnitId adType:(NSString*)adType
{
    [self info:[NSString stringWithFormat:@"%@ video is clicked, id:%@", adType, adUnitId]];
}

// Error callback of any procedure of ad
- (void)adErrorWithAdUnitId:(NSString*)adUnitId adType:(NSString*)adType errorCode:(int)errorCode errorMessage:(NSString*)errorMessage
{
    [self info:[NSString stringWithFormat:@"%@ is error, id:%@, code:%d, message:%@", adType, adUnitId, errorCode, errorMessage]];
}

3. Using recording and sharing functions

Recording function records game interface. Currently only supports contents rendered based on GLKView in iOS.

a）Start and stop recording

Only 1 file can be recorded at one point.

// Start recording
[[HippoRecorder sharedInstance] startRecord];

// Stop recording
[[HippoRecorder sharedInstance] stopRecord];

b）Recording callback method

Set Delegate:

[[HippoRecorder sharedInstance] setDelegate:self];

Realize HPRecorderDelegate Protocol：

#pragma mark - recorder delegate

// Start recording
- (void)recorder:(HippoRecorder*)recorder startRecording:(BOOL)success
{
// ...
}

// Stop recording
// HPRecordFile is the information of the recorded file, including unique ID and file directory
// Notice: the recording file is only stored temporarily at this point. It has not been added to system gallery yet, hence no localIdentifier of the gallery.
- (void)recorder:(HippoRecorder*)recorder stopRecording:(HPRecordFile*)recordFile
{
// ...
}

// Recording error
- (void)recorder:(HippoRecorder*)recorder recordedError:(NSError*)error
{
// ...
}

4. Sharing function

a）Share to Douyin(Tik Tok) right after recording

//  Determine whether Douyin is supported and has authorized
if ( ! [[HippoShareManager sharedInstance] isSupported:HPSharePlatformDouyin] ) {
    [self info:@"Warn: Unsupported for Douyin share."];
    return;
}


// Save the recorded file to gallery to get the necessary gallery file ID for sharing function
[[HippoRecorder sharedInstance] saveAndFetchRecordFile:^(HPRecordFile * _Nonnull recordFile) {

    // Share content
    HPShareContent *shareContent = [[HPShareContent alloc] initWithLocalId:recordFile.localIdentifier];
    // Specify sharing to Douyin
    // Notice that the returned success value means it can jump to Douyin
    // Doesn’t mean sharing succeeds. Refer to callback to see whether sharing succeeds
    BOOL success = [[HippoShareManager sharedInstance] share:shareContent platform:HPSharePlatformDouyin];
    if ( success ) {
        [self info:@"share success."];
    } else {
        [self info:@"share fail."];
    }

} error:^(NSError * _Nonnull error) {
    [self info:[NSString stringWithFormat:@"save record file error. %@", error.localizedDescription ]];
}];