# BuzzAd Benefit - iOS SDK Integration Guide
This documentation provides a guideline for integrating BuzzAd Benefit into an iOS application. With its native format and high performance rewarded ads feature, BuzzAd Benefit can maximize publisher revenue while not hurting the user experience.
## Getting Started
The below items are necessary to proceed with the integration:
- Request the following to Buzzvil's BD manager
- `app_id `
- `unit_id`
- Provide your `postback url` to Buzzvil's BD manager
- Postback API document ([link](https://buzzvil.atlassian.net/wiki/spaces/BDG/pages/396231040/Real-time+Postback+API))
## Installation
### 1. Using Cocoapods (recommended)
#### Add the following line in `Podfile`
```Cocoapods
pod 'BuzzAdBenefit', '1.2.7'
```
### 2. Manual Import
#### 1) Adding framework to the project
Under [Project] > [General] > [Embedded Binaries], add the following frameworks:
- BuzzAdBenefit.framework
- BuzzAdBenefitNative.framework
- AFNetworking.framework
- SDWebImage.framework
- libwebp.framework
(AFNetworking.framework, SDWebImage.framework, libwebp.framework can be downloaded from the Dependencies folder of this Github repository([link](https://github.com/Buzzvil/buzzad-benefit-sdk-publisher-ios/tree/master/Dependencies)))
#### 2) Adding Run script
Under [Project] > [Build Phases], click `+` button and `New Run Script Phase` then paste the script provided below. This process is required to remove the unnecessary architecture in the binary resulted from building a universal framework.
```sh
APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"
find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK; do
FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
EXTRACTED_ARCHS=()
for ARCH in $ARCHS; do
echo "Extracting $ARCH from $FRAMEWORK_EXECUTABLE_NAME"
lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
done
echo "Merging extracted architectures: ${ARCHS}"
lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
rm "${EXTRACTED_ARCHS[@]}"
echo "Replacing original executable with thinned version"
rm "$FRAMEWORK_EXECUTABLE_PATH"
mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"
done
```
## SDK Initialization
### Step 1: Initialize `BuzzAdBenefit`
Please add the following code under `application:didFinishLaunchingWithOptions` of the AppDelegate.
- Insert `app_id` in place of YOUR\_APP\_ID
```objc
// Objective-C
BABConfig *config = [[BABConfig alloc] initWithAppId:YOUR_APP_ID];
[BuzzAdBenefit initializeWithConfig:config];
```
```swift
// Swift
let config = BABConfig(appId: YOUR_APP_ID)
BuzzAdBenefit.initialize(with: config)
```
### Step 2: Set `UserProfile` of the user
`UserProfile` needs to be established at user login.
> **Note** : User ID and targeting information (gender, birth year) is necessary for proper operation of BuzzAd Benefit. **Advertisements are served only after the `setUserProfile` method is called.**
- **userId** : A unique identifier assigned to each user
- _If there may be cases where `userId` can change, please talk to the BD manager in advance._
- e.g.: `userId` changes when user reinstalls the app after deletion
- **gender**
- `BABUserGenderMale`
- `BABUserGenderFemale`
- **birthYear**
```objc
// Objective-C
BABUserProfile *userProfile = [[BABUserProfile alloc] initWithUserId:YOUR_SERVICE_USER_ID birthYear:1985 gender:BABUserGenderMale];
[BuzzAdBenefit setUserProfile:userProfile];
```
```swift
// Swift
let userProfile = BABUserProfile(userId: YOUR_SERVICE_USER_ID, birthYear: 1985, gender: BABUserGenderMale)
BuzzAdBenefit.setUserProfile(userProfile)
```
> **Note** : Once session key registration is complete via Step 1 and 2, `BABSessionRegisteredNotification` notification is sent. Without the session key, the API key to receive advertisement from the server, the SDK cannot load any advertisements. However, if the time interval between Step 2 and the ad request is too short, the below is needed for session key registration.
```objc
// Objective-C
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(loadBABAd) name:BABSessionRegisteredNotification object:nil];
```
```swift
// Swift
NotificationCenter.default.addObserver(self, selector: #selector(loadBABAd), name: NSNotification.Name.BABSessionRegistered, object: nil)
```
### Step 3: Set `UserPreference` of the user
`UserPreference` needs to be established at user login.
- `autoplayType(AutoplayType autoplayType)`: Configures video autoplay method.
- `AutoplayType.ENABLED`: Video autoplay is allowed
- `AutoplayType.ON_WIFI`: Video autoplay is allowed only on WiFi
- `AutoplayType.DISABLED` (default): Video autoplay is disabled
```objc
// Objective-C
BABUserPreference *userPreference = [[BABUserPreference alloc] initWithAutoPlayType:BABVideoAutoPlayEnabled];
[BuzzAdBenefit setUserPreference:userPreference];
```
```swift
// Swift
let userPreference = BABUserPreference(autoPlayType: BABVideoAutoPlayEnabled)
BuzzAdBenefit.setUserPreference(userPreference)
```
### Step 4. Delete user setting
`UserProfile` and `UserPreferences` needs to be deleted upon user logout.
```objc
// Objective-C
[BuzzAdBenefit setUserProfile:nil];
[BuzzAdBenefit setUserPreference:nil];
```
```swift
// Swift
BuzzAdBenefit.setUserProfile(nil)
BuzzAdBenefit.setUserPreference(nil)
```
### Step 5. Proceed to native ads integration
- [Native Ads Type](Native-Ads-Type)
## Advanced Usage
### Customized ad launcher
Publisher can choose modify the way ad is loaded by implementing a customized ad launcher.
> **Note** : Please do not modify the click URI from the launcher. This may cause issue in ad tracking and result in incorrect statistics.
>
1) Create `BABLauncher`. The parameter for `openUrl:object:userInfo` contain either `BABAd` or `BABArticle`.
```objc
// Objective-C
@interface BABCustomLauncher : NSObject
@end
@implementation BABCustomLauncher
- (void)openUrl:(NSURL *)url object:(id)object userInfo:(nullable NSDictionary *)userInfo {
if ([object isKindOfClass:BABAd.class]) {
BABAd *ad = object;
NSString *unitId = ad.unitId;
NSString *title = ad.creative.title;
}
...
[UIApplication.sharedApplication openURL:url options:@{} completionHandler:nil];
}
@end
```
```swift
// Swift
class BABCustomLauncher: NSObject, BABLauncher {
func open(_ url: URL, object: Any?, userInfo: [AnyHashable : Any]? = nil) {
if let ad = object as? BABAd {
let unitId = ad.unitId
let title = ad.creative.title
}
...
UIApplication.shared.open(url, options: nil, completionHandler: nil)
}
}
```
> Note : There are times when users leave the app through the deeplinks in the ads and there needs to be a way for users to return to the original page when back button is clicked. For such ads, `ad.creative.isDeeplink` will return `YES`.
2) Set customized ad launcher to `BuzzAdBenefit`.
```objc
// Objective-C
BABCustomLauncher *launcher = [[BABCustomLauncher alloc] init];
[BuzzAdBenefit setLauncher:launcher];
```
```swift
// Swift
let adLauncher = BABCustomLauncher()
BuzzAdBenefit.setLauncher(launcher)
```
### Error information on ad loading failure
The error information can be found via `code` of `BABError` retrieved as callback parameter.
```objc
typedef enum {
BABUnknownError = 0,
BABServerError,
BABInvalidRequest,
BABRequestTimeout,
BABEmptyResponse
} BABErrorCode;
```
### VoC page for CPA-type ads
There are times when users do not receive the reward for their follow-through actions from the ads due to various reasons. Consequently, we have prepared a webpage in the SDK where users can report such issues.
1) Design icon/tab for loading VoC page like the example below.
2) Upon clicking icon/tab, call `[BuzzAdBenefit showInquiryPageOnViewController:viewController]` method.
## Change Log
| Version | Date | Content | Person in Charge |
| ------- | ---------- | ------------------------- | ---------------- |
| 1.0 | 2019-10-03 | English doc for SDK 1.2.7 | Ryan Ko |