iOS

1. 사전 요구사항

• XCode

• Minimum iOS Version : 16

적용할 SDK 최신 버전은 CHANGELOG.md 파일을 참고해주세요.

2. SDK Integration

2.1 SDK 추가하기

SDK 는 Swift Package Manager (SPM)을 사용하거나 CocoaPod를 사용하여 XCode Project 에 추가할 수 있습니다. 또는 직접 다운로드 하여 추가하는 것도 가능합니다.

Swift Package Manager

XCode 의 상단 메뉴에서 File > Add Package Dependencies 를 클릭하고 아래 주소를 사용하여 패키지를 추가합니다.

https://github.com/snapplay-io/ios_offerwall_sdk

나중에 SDK 버전이 올라가는 경우에는 File > Packages > Update to Latest Package Versions 를 클릭하여 SDK 버전을 최신버전으로 적용할 수 있습니다.

CocoaPods

XCode Project 폴더에 아래와 같이 Podfile 을 작성합니다.

platform :ios, '16.0'
use_frameworks!

target 'YourProject' do
  pod 's2offerwall', '~> 1.0.25'
end

Podfile.lock으로 버전이 고정된 경우 갱신을 위해 pod을 업데이트합니다.

% pod update

최신 pod 목록으로 업데이트하고 라이브러리를 설치합니다.

% pod repo update
% pod install

YourProject.xcworkspace 파일을 사용하여 XCode Project 를 open 합니다.

CocoaPod 사용하여 개발 진행시 rsync ... 와 같은 에러가 발생하는 경우에는 아래와 같이 조치합니다.

• Xcode project 에서 project target 을 선택합니다.

• Build Settings 에서 "User Script Sandboxing." 을 찾아 설정을 NO 로 변경합니다.

Xcode의 User Script Sandboxing 기능은 rsync가 특정 디렉터리에 접근하거나 쓰는 것을 제한할 수 있습니다.

이것은 최신 Xcode 버전에서 흔히 발생하는 문제입니다.

Library File 다운로드

Framework Library 파일을 다운로드 받아서 직접 XCode Project 에 설정할 수 있습니다.

https://github.com/snapplay-io/ios_offerwall_sdk 의 sdk 폴더에서 최신버전의 라이브러리 파일을 다운로드 받으세요.

압축을 풀면 s2offerwall.xcframework 폴더가 나타납니다. 해당 폴더를 아래 그림과 같이 XCode Project 에 Drag 해서 넣은 후 Embed 설정을 Embed & Sign 으로 변경합니다.

2.2 APP ID 설정하기

고객사 페이지에 매체를 생성하여 APP_ID 를 발급 받습니다. 발급 받은 APP_ID 를 info.plist 파일에 등록합니다. 또는 SDK 초기화 전에 별도의 API 를 호출하여 APP_ID 를 설정할 수 있습니다.

Swift

// APP_ID 를 별도 API 를 호출하여 설정할 수 있습니다.
S2Offerwall.setAppId("YOUR_APP_ID")

Objective-C

// APP_ID 를 별도 API 를 호출하여 설정할 수 있습니다.
[S2Offerwall setAppId:@"YOUR_APP_ID"];

이때 필요한 권한 문구를 같이 등록해주세요. 필요한 권한은 아래와 같습니다.

• Privacy - Photo Library Usage Description

• Privacy - Camera Usage Description

  • 위 2개 권한은 스크린샷 등록이 필요한 광고 참여 시에 필요합니다.

• Privacy - Tracking Usage Description

  • 이 권한은 광고 ID (IDFA) 값을 획득하기 위하여 필요합니다.

2.3 SDK 초기화

SDK 사용 전에 초기화 API 를 호출합니다. 초기화 결과를 전달받기 위하여 InitializeListener 프로토콜 또는 클로저 함수를 사용할 수 있습니다.

Swift

public class S2Offerwall : NSObject {

    public static func initSdk(_ listener:S2OfferwallInitializeListener?)
    
    public static func initSdk(onCompletion:@escaping (Bool) -> ())
    
}   

Objective-C

@interface S2Offerwall : NSObject

+ (void)initSdk:(nullable id<S2OfferwallInitializeListener>)listener;

+ (void)initSdkWithCompletion:(void (^)(BOOL success))completion;

@end

Swift

public protocol S2OfferwallInitializeListener : NSObjectProtocol {

    optional func onSuccess()

    optional func onFailure()

}

Objective-C

@protocol S2OfferwallInitializeListener <NSObject>

@optional
- (void)onSuccess;

@optional
- (void)onFailure;

@end

호출 예시

Swift

// InitializeListener Sample
import UIKit
import s2offerwall

class ViewController: UIViewController, S2OfferwallInitializeListener {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view.
        
        S2Offerwall.initSdk(self)
    }

    func onSuccess() {
        NSLog("on Success")
    }
    
    func onFailure() {
        NSLog("on Failure")
    }
}

// Closure Sample
import UIKit
import s2offerwall

class ViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view.
        
        S2Offerwall.initSdk() { succ in
            if (succ) {
                NSLog("init succcess")
            }
            else {
                NSLog("init failure")
            }
        }
    }
    
}

Objective-C

// InitializeListener Sample
#import "ViewController.h"
#import <s2offerwall/s2offerwall-Swift.h>

@interface ViewController () <S2OfferwallInitializeListener>
@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    // Do any additional setup after loading the view.
    
    [S2Offerwall initSdk:self];
}

- (void) onSuccess {
    NSLog(@"on success");
}

- (void) onFailure {
    NSLog(@"on Failure");
}

@end

// onCompletion block Sample
#import "ViewController.h"
#import <s2offerwall/s2offerwall-Swift.h>

@interface ViewController ()
@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    // Do any additional setup after loading the view.
    
    [S2Offerwall initSdkOnCompletion:^(BOOL succ) {
        if (succ) {
            NSLog(@"on success");
        }
        else {
            NSLog(@"on Failure");
        }
    }];
}

@end

2.4 사용자 식별값 설정하기

광고 참여를 위해서는 사용자 식별값이 설정되어야합니다. 일반적으로 매체의 로그인 ID 가 사용되며 아래의 API 를 호출하여 SDK 에 사용자 식별값을 설정합니다. 이렇게 설정된 식별값은 이후 사용자가 광고 참여를 완료하는 시점에 매체의 서버로 Postback 이 호출되는데 그때 pub_user_nm 파라메터로 전달됩니다.

사용자 식별값의 경우 로그인 ID 를 바로 사용하지 마시고 개인 정보 이슈가 없도록 가급적 Hash 또는 암호화된 값으로 전달해주시기 바랍니다.

Swift

// 사용자 식별값 설정하기
S2Offerwall.setUserName(_ userName:String [, displayName:String])

// 설정된 사용자 식별값 삭제하기
S2Offerwall.resetUserName()

Objective-C

// 사용자 식별값 설정하기
[S2Offerwall setUserName:(NSString *)userName displayName:(NSString *)displayName];

// 설정된 사용자 식별값 삭제하기
[S2Offerwall resetUserName];

SDK v1.0.19 부터 setUserName() 에 displayName 파라메터가 추가되었습니다. 해당 파라메터는 오퍼월내 이벤트에서 랭킹 등을 표시할 때 사용되며 유저의 앱 내 닉네임 등으로 전달해주시면 됩니다. Snap 오퍼월의 다양한 이벤트들을 100% 활용하기 위하여 displayName 파라메터가 필요하므로 가급적 적용해주시기 바랍니다.

유저의 닉네임등이 노출되면 안되는 경우에는 원하시는 형태로 마스킹 처리 후 (예: 우리****) 전달해주시기 바랍니다.

3. 오퍼월 띄우기

3.1 EventListener

오퍼월 내에서 발생하는 이벤트를 처리하기 위하여 EventListener 를 구현하여 설정해야합니다. iOS 의 경우 2종류의 이벤트가 발생할 수 있습니다.

• 사용자가 광고 참여하는 시점에 아직 사용자 식별값이 설정되어 있지 않다면 onLoginRequested() 가 호출됩니다.

• 오퍼월이 닫혀야하는 시점에 onCloseRequested() 가 호출됩니다. 대부분의 경우는 SDK 내부에서 처리되지만 만약 OfferwallView 를 직접 생성하여 화면을 구성한 경우에는 적절한 액션을 수행하도록 구현해야합니다.

아래는 EventListener 인터페이스와 그 사용 예시입니다.

Swift

public protocol S2OfferwallEventListener : NSObjectProtocol {

    optional func onLoginRequested(_ param:String?)

    optional func onCloseRequested(_ param:String?)

}

Objective-C

@protocol S2OfferwallEventListener <NSObject>

@optional
- (void)onLoginRequested:(nullable NSString *)param;

@optional
- (void)onCloseRequested:(nullable NSString *)param;

@end

아래는 Global EventListener 를 설정하는 예시입니다.

Swift

class ViewController: UIViewController, S2OfferwallEventListener {
        
    override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view.
        
        S2Offerwall.initSdk() { result in
            if (result) {
                NSLog("init succcess")
            }
            else {
                NSLog("init failure")
            }
        }
        
        S2Offerwall.setEventListener(self)
    }
    
    // S2Offerwall.EventListener
    func onLoginRequested(param:String?) {
        S2Offerwall.setUserName(getLoginId(),getUserNickname())
    }
    
    // ...
}

Objective-C

#import "ViewController.h"
#import <s2offerwall/s2offerwall-Swift.h>

@interface ViewController () <S2OfferwallEventListener>
@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    // Do any additional setup after loading the view.
    
    [S2Offerwall initSdkOnCompletion:^(BOOL succ) {
        if (succ) {
            NSLog(@"on success");
        }
    }];
    
    [S2Offerwall setEventListener:self];
}

- (void) onLoginRequested:(NSString *)param {
    [S2Offerwall setUserName:[self getLoginId] displayName:[self getUserNickname]];
}

// ...
@end

3.2 로그인 지연 처리

일반적으로 사용자가 앱에 로그인 하는 시점에 setUserName() 을 호출하여 SDK 에 사용자 식별값을 설정합니다. 하지만 사용자 식별값이 설정되지 않았어도 오퍼월 이용은 가능합니다.

사용자의 적극적인 참여를 위하여 우선 오퍼월을 경험하게 한 후 사용자 식별값이 꼭 필요한 시점 (광고 참여 또는 이용문의)에 로그인을 수행하도록 처리할 수 있습니다. 이를 위하여 EventListener의 onLoginRequest() 를 이용합니다.

onLoginRequest() 가 호출되면 앱의 로그인 페이지로 이동시킨 후 사용자가 로그인을 완료하면 setUserName() 을 호출하여 사용자 식별값을 설정해줍니다. 이후 로그인 페이지를 닫으면 오퍼월로 재진입되어 사용자 액션을 이어서 진행할 수 있습니다.

3.3 S2OfferwallViewController

오퍼월을 별도의 UIViewController 로 띄워줍니다. 표시하고자 하는 오퍼월의 플레이트먼트 명칭을 파라메터로 전달해야합니다. 플레이스먼트는 Snapplay 사이트에서 설정할 수 있습니다.

Swift

// Modal 창으로 띄워줍니다.
S2Offerwall.presentOfferwallInternal(_ viewController: UIViewController, 
                                        placementName: String)
             
// NavigationController 를 사용하여 push 방식으로 띄워줍니다.                           
S2Offerwall.pushOfferwallInternal(_ navigationController: UINavigationController, 
                                           placementName: String)

Objective-C

// Modal 창으로 띄워줍니다.
[S2Offerwall presentOfferwall:(UIViewController *)vc 
                placementName:(NSString *)name];
                
// NavigationController 를 사용하여 push 방식으로 띄워줍니다.
[S2Offerwall pushOfferwall:(UINavigationController *)nc 
             placementName:(NSString *)name];

그리고 오퍼월에는 "main" 이라는 이름의 특수한 형태의 오퍼월이 있습니다. 메인 오퍼월은 여러개의 플레이스먼트 오퍼월을 조합하여 하나의 화면에 표시해주는 오퍼월입니다. 메인 오퍼월을 띄우고자 할 때에는 플레이스먼트 이름 대신에 별도로 정의된 S2Offerwall.MAIN 을 지정합니다.

S2OfferwallViewController 는 전역 EventListener 를 설정해야하며 만약 present...() 또는 push...() 시점에 SDK 초기화가 되어 있지 않았다면 내부에서 먼저 초기화 수행하고 그 이후에 오퍼월을 표시합니다.

3.4 S2OfferwallView

오퍼월을 표시하는 View 클래스입니다. 오퍼월을 매체의 특정 영역에 표시하고자 할 경우 사용할 수 있습니다. S2OfferwallView 를 생성하고 원하는 영역에 추가한 후에 EventListener 를 설정하고 이후 load() 함수를 호출하여 원하는 오퍼월을 표시합니다.

S2OfferwallView 는 EventListener 대신 Closure 를 사용하여 이벤트를 처리할 수 있습니다.

아래는 S2OfferwallView 를 사용하는 예시입니다.

Swift

private func createOfferwallView() {
        
    let owView = S2OfferwallView()
    view.addSubview(owView)
    
    owView.translatesAutoresizingMaskIntoConstraints = false
    
    owView.leftAnchor.constraint(equalTo: view.leftAnchor).isActive = true
    owView.rightAnchor.constraint(equalTo: view.rightAnchor).isActive = true
    owView.topAnchor.constraint(equalTo: view.topAnchor).isActive = true
    owView.bottomAnchor.constraint(equalTo: view.bottomAnchor).isActive = true
    
    // set EventListener
    owView.setEventListener(self)
    
    S2Offerwall.initSdk() { succ in
        if (succ) {
            owView.load(placementName: "your_placement_name")
        }
    }
}

Objective-C

- (void)createOfferwallView {
    S2OfferwallView *owView = [[S2OfferwallView alloc] init];
    [self.view addSubview:owView];
    
    owView.translatesAutoresizingMaskIntoConstraints = NO;
    
    // NSLayoutAnchor를 사용한 제약
    [NSLayoutConstraint activateConstraints:@[
        [owView.leftAnchor constraintEqualToAnchor:self.view.leftAnchor],
        [owView.rightAnchor constraintEqualToAnchor:self.view.rightAnchor],
        [owView.topAnchor constraintEqualToAnchor:self.view.topAnchor],
        [owView.bottomAnchor constraintEqualToAnchor:self.view.bottomAnchor]
    ]];
    
    // set EventListener
    [owView setEventListener:self];
    
    [S2Offerwall initSdkOnCompletion:^(BOOL succ) {
        if (succ) {
            [owView loadWithPlacementName:@"your_placement_name"];
        }
    }];
}

3.4 앱 추적 동의 설정

iOS 14 부터는 IDFA에 대한 추적 허용을 명시적으로 사용자에게 동의 받도록 정책이 변경되었습니다. 앱 추척(App Tracking Transparency, ATT) 동의창을 띄우기 위해서는 우선 info.plist 파일에 Tracking Usage Description 항목을 작성해야합니다. (2.2 APP_ID 설정하기 참고).

이후 앱 추적 동의 창을 띄우기 위한 iOS API 를 호출합니다. 또는 SDK가 제공하는 편의 함수를 호출하실 수 있습니다. 앱 추적 동의 창은 앱이 시작되는 시점에 띄우는 것을 권장합니다.

Swift

// ATT 팝업을 띄우는 편의 함수입니다.
S2Offerwall.presentATTPopup(_ viewController:UIViewController)

Objective-C

[S2Offerwall presentATTPopup:(UIViewController *)vc];

4. Sample Code

아래는 버튼을 클릭하면 S2OfferwallViewController 를 Modal 창으로 띄우는 가장 간단한 구현 코드입니다.

Swift

import UIKit
import s2offerwall

class ViewController: UIViewController, S2OfferwallEventListener {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view.
        
        S2Offerwall.presentATTPopup(self)
        
        S2Offerwall.setEventListener(self)
    }
    
    @IBAction 
    func buttonTapped() {
        S2Offerwall.presentOfferwall(self, placementName:S2Offerwall.MAIN)
    }
    
    // S2Offerwall.EventListener
    func onLoginRequested(param:String?) {
        S2Offerwall.setUserName(getLoginId(), getUserNickname())
    }
    
    private func getLoginId() -> String {
        return "your_login_id" // implements your own codes
    }
    
    private func getUserNickname() -> String {
        return "화면 표시용 명칭" // implements your own codes
    }
}

Objective-C

#import "ViewController.h"
#import <s2offerwall/s2offerwall-Swift.h>

@interface ViewController () <S2OfferwallEventListener>
@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    // Do any additional setup after loading the view.
    
    [S2Offerwall presentATTPopup:self];
    
    [S2Offerwall setEventListener:self];
}

- (IBAction)buttonTapped:(id)sender {
    [S2Offerwall presentOfferwall:self placementName:S2Offerwall.MAIN];
}

- (void) onLoginRequested:(NSString *)param {
    [S2Offerwall setUserName:[self getLoginId] displayName:[self getUserNickname]];
}

- (NSString *) getLoginId {
    return @"your_login_id"; // implements your own codes
}

- (NSString *) getUserNickname {
    return @"화면 표시용 명칭"; // implements your own codes
}
@end

5. Privacy Manifests

Privacy Accessed API Types

Privacy Accessed API Type	Privacy Accessed API Reasons
User Defaults	CA92.1: Access info from same app, per documentation

Privacy Nutrition Label Types

-	Collected Data Type	Collection Purposes	Linked	Tracking
Contact Info	Email Address	App Functionality	YES	NO
User Content	Photos or Videos	App Functionality	YES	NO
	Customer Support	App Functionality	YES	NO
Identifiers	Device ID	Third-Party Advertising	YES	YES
Usage Data	Product Interaction	Analytics App Functionality	YES	NO
	Advertising Data	App Functionality Third-Party Advertising	YES	YES