고급 설정

사용자 ID 설정

오퍼월 광고 유닛이나 아이언소스 보상형 광고 유닛에서 유저 보상을 위해 서버간 콜백을 사용하는 경우, setUserID 메서드를 사용하여 각 사용자 별로 고유 식별자(UserID)를 정의해야 합니다.

사용자 관련 데이터 손실을 방지하기위해서는, UserID는 초기화 요청 이전에 설정해야 합니다. 최대 64자로 구성된 NSString 형식으로 된 고유 식별자를 사용해 주세요.

[IronSource setUserId:YOUR_USERID];
IronSource.setUserId(userID)
Note: UserID가 모든 사용자 별로 고유하게 부여될 수 있도록 IDFA를 식별자로 사용하지 말아주시기 바랍니다. 

세그먼트 정의

아이언소스 SDK의 세그먼트 기능을 통해 특정 광고 시청자에 맞게 광고 제공방식을 쉽게 조정할 수 있습니다. 아이언소스 SDK가 사용자의 세그먼트를 분류하도록 하려면 레벨플레이 플랫폼 서버에 사용자들의 세부 정보를 전달하여야 합니다.

아이언소스는 사용자 구분을 위해 아래의 세 가지 데이터 전달 방식을 지원합니다:

  • 기기 속성 정보: 아이언소스 SDK는 위치, 기기 모델, 기기 제조사, 앱 버전, OS 등과 같은 사용자의 기기에 존재하는 표준 파라미터들을 자동으로 수집합니다. 해당 데이터들은 별도로 송신하지 않아도 됩니다. (위치의 경우 도시 수준의 위치까지만 수집)
  • 사용자 속성 정보: 나이, 성별, 생성일과 같은 포괄정 유저데이터(지원되는 전체 세그먼트 속성 및 설명 목록은 아래에 있는 항목을 참조)는 API를 통해서만 전달되어야 합니다. 아이언소스 SDK가 레벨플레이 플랫폼에서 정의된 세그먼트들에 기반해 다양한 사용자를 분류할 수 있도록 지침을 따라 유저 상세 정보를 보내주시면 됩니다.
  • 커스텀 세그먼트: 유저 상세 정보들을 레벨플레이 서버에 보내지 않고 직접 커스텀 세그먼트를 생성하고 그 설정에 맞게 광고 조정할 수 있습니다.
동적 세그먼트 구분 아이언소스 SDK 7.2.0 이상부터는 ISSegment API로 세션 중에 세그먼트를 변경할 수 있습니다.
이렇게 변경된 사항은 변경 이후 로딩되는 광고부터 적용되며, 광고 워터월의 동적조정을 위해 각각의 광고 유닛 로딩 전에 호출할 수 있습니다.
아이언소스 세그먼트에 대한 자세한 설명은 여기를 참고 부탁 드립니다.

사용자 속성 정보 전달하기

레벨플레이 플랫폼 상에서 세그먼트 정의가 완료되었으면 유저 별 특정 정보를 레벨플레이 서버에 알려야 합니다.

먼저, 세그먼트 객체를 초기화합니다:

ISSegment *segment = [[ISSegment alloc]init];
let segment: ISSegment = ISSegment()

세그먼트의 기반이 될 속성을 정의하고 아이언소스 서버로 전달합니다. 아래 중 한 가지 방법으로 이 정보들을 전송할 수 있습니다:

  1. 사용자가 속한 세그먼트가 이미 알고 있는 세그먼트라면 아래와 같이 세그먼트 명칭을 지정합니다:
    [segment setSegmentName:YOUR_SEGMENT_NAME];
    segment.segmentName = "YOUR_SEGMENT_NAME"
  2. 유저 상세 정보를 전송합니다. 아이언소스는 API 상에서 사용자를 세그먼트로 분류하기 위해 설정할 수 있는 다양한 표준 사용자 속성을 제공합니다. 아래로 스크롤하여 지원되는 사용자 세그먼트 속성들을 확인하세요:
    // Set user age
    [segment setAge:USER_AGE]; 
    // Set user gender
    [segment setGender:USER_GENDER];
    // Set user level
    [segment setLevel:USER_LEVEL];
    // Set user's paying status
    [segment setPaying:USER_PAYING];
    // Set user's total in-app purchase history
    [segment setIapTotal:YOUR_IAP_TOTAL];
    // Set user creation date
    [segment setUserCreationDate:YOUR_DATE];
    // Set user age
    segment.age = USER_AGE
    // Set user gender
    segment.gender = ISGender.IRONSOURCE_USER_FEMALE
    // Set user's total in-app purchases
    segment.iapTotal = USER_IAP_TOTAL
    // Set user's level
    segment.level = USER_LEVEL
    // Set user's paying status
    segment.paying = USER_PAYING_STATUS
    // Set user creation date
    segment.userCreationDate = NSDate() as Date!
  3. 또한, 세그먼트 당 5개의 커스텀 사용자 속성 설정이 가능합니다:

    [segment setCustomValue:YOUR_CUSTOM_VALUE forKey:YOUR_CUSTOM_KEY];
    segment.setCustomValue("CUSTOM_VALUE", forKey: "CUSTOM_KEY")

    다음으로, 사용자 맞춤 경험을 위한 세그먼트 기반 광고 유닛 게재를 위해, 세그먼트 명칭이나 사용자 속성 중 하나로 아래의 함수 호출을 완료하세요:

    [IronSource setSegment:YOUR_SEGMENT];
    IronSource.setSegment(YOUR_SEGMENT);

지원되는 사용자 세그먼트의 속성

세그먼트 속성 타입 제약 설명
segmentName String
  • 영문자/숫자
  • 최대 32자
아이언소스 계정 내에 정의된 세그먼트의 명칭
Age Int 1-99 사용자의 나이(만)
Gender enum IRONSOURCE_USER_MALE or IRONSOURCE_USER_FEMALE 사용자의 성별
Paying Boolean Yes or No (Objective-C) / true or false (Swift)
  • 사용자가 인앱 결제를 한 이력이 있을 경우 Yes 또는 true
  • 사용자가 인앱결제를 한 이력이 없을 경우 No 또는 false
iap_total Double 1-999999.99 사용자가 인앱결제에 사용한 총 금액 수
userCreationDate NSDate Cannot be smaller than 0 유저가 앱을 설치한 날짜 (millisecond 단위)
Custom Parameters key=string, value=string
  • 아이언소스는최대 5개의 커스텀 속성 파라미터 지원
  • 영문자/숫자
  • 최대 32자
아이언소스 서버에 보낼 추가 유저 데이터

사용자가 속한 세그먼트 명칭 받기

  1. ISSegmentDelegate 인터페이스를 클래스에 구현하여 Segment Name 프로토콜에 따르도록 하고 세그먼트 명칭 수신을 활성화 합니다.
  2. 사용자가 속한 세그먼트 명칭을 획득할 수 있도록 아래의 대리자 (Delegate)를 등록합니다. SDK는 이후 해당 이벤트 발생 정보를 전달할 것입니다.
  3. 
    [IronSource setSegmentDelegate:self];
    (void)didReceiveSegement:(NSString *)segment
    
    
    IronSource.setSegmentDelegate(self)
    func didReceiveSegement(_ segment: String!)
    

커스텀 파라미터

아이언소스 SDK는 보상형 동영상 광고 및 오퍼월 광고에 대해 커스텀 파라미터를 제공합니다. 광고 유닛 초기화 시 커스텀 파라미터들을 설정 및 전달하고 사용자의 보상 조건 완료 이벤트 시에 해당 파라미터들을 전달받을 수 있습니다.

이제 유니티 레벨플레이 상의 모든 미디에이션 네트워크들에 대해서 커스텀 파라미터를 전달할 수 있습니다.

Note:
  1. 커스텀 파라미터는 서버간 완료 콜백 사용시에만 사용할 수 있습니다. 콜백 문자열의 일부로 해당 파라미터가 전달됩니다.
  2. 초기화 요청 시 1개 이상의 커스텀 파라미터 입력도 가능합니다.

구현 코드

보상형 동영상 광고

Note:
  • 커스텀 파라미터 들은 각 세션 중에 여러번 설정될 수 있습니다.
  • 값을 초기화 하려면 clearRewardedVideoServerParameters 값을 사용해서 기존 값을 삭제하고 새로운 값을 설정해 주세요.

[IronSource setRewardedVideoServerParameters:(NSDictionary *)parameters];
[IronSource clearRewardedVideoServerParameters];

IronSource.setRewardedVideoServerParameters(parameters: [AnyHashable : Any])
IronSource.clearRewardedVideoServerParameters()

오퍼월 광고

Note:
  • 커스텀 파라미터들 showOW 호출 전에 호출되어야 합니다.

NSMutableDictionary * owDic = [[NSMutableDictionary alloc] init];
owDic[@"ip"] = @"1.0.0.9";
[ISConfigurations configurations].offerwallCustomParameters = owDic;

var owDic: [AnyHashable: Any] = [:]
owDic["ip"] = "1.0.0.9"
ISConfigurations.getConfigurations().offerwallCustomParameters = owDic

구현 예제

예를 들어, 오퍼월 광고를 사용하는 사용자의 IP를 받고자 할 경우, 이를 보상 조건 완료 콜백에 추가 파라미터로 설정할 수 있습니다:


NSMutableDictionary * owDic = [[NSMutableDictionary alloc] init];
owDic[@"ip"] = @"1.0.0.9";
[ISConfigurations configurations].offerwallCustomParameters = owDic;

var owDic: [AnyHashable: Any] = [:]
owDic["ip"] = "1.0.0.9"
ISConfigurations.getConfigurations().offerwallCustomParameters = owDic

이후, 아래 예시의 URL에서와 같이 대응하는 콜백을 받을 수 있습니다:

http://www.mydomain.com/rewardsCallback?appUserId=[USER_ID]&rewards=[REWARDS]&eventId=[EVENT_ID]&itemName=[ITEM_NAME]&custom_ip=1.0.0.9
 

워터폴 구성 설정을 통한 가격 제한 (베타)

워터폴 구성 설정 API는 워터폴 상에 동적으로 최소 또는 최대 가격 제한을 설정할 수 있는 API입니다. 이 API를 통해 제한을 설정해서 사용자 별로 반환되는 워터폴을 동적으로 조정하면 광고 로딩 횟수 및 지연 시간을 줄일 수 있습니다.

제한 설정을 할 수 있는 항목은 다음과 같으며, 각 항목들은 모두 동시에 설정 가능합니다:

설정 항목 타입 설명
ceiling double 비(非)경매 인스턴스의 최대 eCPM값 (USD)
floor double 비(非)경매 인스턴스 및 경매 인스턴스의 최소 eCPM 값 (USD)

워터폴 구성 설정 생성하기

ISWaterfallConfiguration 객체는 워터폴을 커스터마이징하거나 선별하는 구성 내용을 포함합니다.
워터폴 구성을 생성하려면, ISWaterfallConfigurationBuilder를 사용합니다:

// define a WaterallConfigurationBuilder
ISWaterfallConfigurationBuilder *builder = [ISWaterfallConfiguration builder];
// Build the WaterfallConfiguration and add data to constrain or control a waterfall
[builder setCeiling:@ceiling];
[builder setFloor:@floor];
ISWaterfallConfiguration *configuration = [builder build];
//set a configuration for an ad unit
[IronSource setWaterfallConfiguration:configuration forAdUnit:[ISAdUnit IS_AD_UNIT_REWARDED_VIDEO]];
// Build the WaterfallConfiguration and add data to constrain or control a waterfall
let configuration = ISWaterfallConfiguration.builder()
    .setCeiling(10.05)
    .setFloor(1.01)
    .build()
//set a configuration for an ad unit
IronSource.setWaterfallConfiguration(configuration, for: ISAdUnit.is_AD_UNIT_REWARDED_VIDEO())

워터폴 구성 삭제하기

세션 도중에도 워터폴 구성을 변경이 가능합니다. 구성을 삭제하려면 ISWaterfallConfiguration.clear() 함수를 사용하세요:

ISWaterfallConfiguration *clearConfiguration = [ISWaterfallConfiguration clear];
[IronSource setWaterfallConfiguration:clearConfiguration forAdUnit:[ISAdUnit IS_AD_UNIT_REWARDED_VIDEO]];
let clearConfiguration = ISWaterfallConfiguration.clear();

IronSource.setWaterfallConfiguration(clearConfiguration, for: ISAdUnit.is_AD_UNIT_REWARDED_VIDEO());

워터폴 구성 덮어쓰기

생성된 ISWaterfallConfiguration 객체는 변경이 불가능하기 때문에, 현재 구성을 변경하려면 새로운 ISWaterfallConfiguration 객체를 생성해야 합니다. 마찬가지로 ISWaterfallConfigurationBuilder를 사용하여 새 ISWaterfallConfiguration을 정의하면 됩니다.

...
[IronSource setWaterfallConfiguration:configuration forAdUnit:[ISAdUnit IS_AD_UNIT_REWARDED_VIDEO]];
ISWaterfallConfigurationBuilder *builder2 = [ISWaterfallConfiguration builder];
[builder2 setCeiling:@ceiling];
[builder2 setFloor:@floor];
ISWaterfallConfiguration *configuration2 = [builder build];
[IronSource setWaterfallConfiguration:configuration2 forAdUnit:[ISAdUnit IS_AD_UNIT_REWARDED_VIDEO]];
...
IronSource.setWaterfallConfiguration(configuration, for: ISAdUnit.is_AD_UNIT_REWARDED_VIDEO())
let configuration2 = ISWaterfallConfiguration.builder()
    .setCeiling(ceiling)
    .setFloor(floor)
    .build()
IronSource.setWaterfallConfiguration(configuration2, for: ISAdUnit.is_AD_UNIT_REWARDED_VIDEO())

아이언소스 SDK 에러 코드

아이언소스는 아이언소스 SDK 연동 상의 실패 사항에 대한 설명을 제공하기 위해 오류 피드백 메커니즘을 제공합니다. 문제가 발생했거나, 연동 중 일부분이 올바르게 완료되지 않은 경우 아래에 등재된 오류가 발생합니다.

ironSource Error 오브젝트에는 에러 코드메시지가 포함됩니다. 아래는 발생 가능한 에러들과 해당 기능에 따른 메시지 들입니다.

에러 코드 광고 유닛(유형) 설명
508 N/A
  • 미디에이션 / 네트워크 초기화 실패
  • Demand Only 모드가 아닌 모드에서 Demand Only API 호출
  • Demand Only모드에서 Demand Only API가 아닌 API를 호출
509 인터스티셜 송출 실패: 송출할 광고가 없음
보상형 동영상
오퍼월
510 인터스티셜 로드 실패: 서버 응답 실패
로드 실패: 아답터 로딩 실패
520 인터스티셜 송출 실패: 인터넷 연결 없음
(ShouldTrackNetworkState가 활성화 되어 있는 상태)
보상형 동영상 송출 실패: 인터넷 연결 없음
오퍼월
524 인터스티셜 송출 실패: 플레이스먼트 %@가 설정된 광고 빈도 한도를 초과
송출 실패: 플레이스먼트 %@가 설정된 광고 빈도 한도를 초과
보상형 동영상
오퍼월
525 인터스티셜 송출 실패: 광고 유닛에 설정된 광고 빈도 한도를 초과
송출 실패: 광고 유닛에 설정된 광고 빈도 한도를 초과
보상형 동영상
배너
526 인터스티셜 송출 실패: 광고 유닛에 설정된 세션당 일일 광고 횟수 한도를 초과
보상형 동영상
1007 인터스티셜 광고 경매 실패: 경매 요청에 필요한 정보가 포함되어 있지 않음
보상형 동영상
1022 보상형 동영상 송출 실패: 다른 보상형 동영상 광고 재생중에 보상형 동영상 광고 재생할 수 없음
1023 보상형 동영상 송출 실패: 송출할 수 있는 광고가 없는 상태에서 광고 송출 API 호출
1036 인터스티셜 송출 실패: 다른 인터스티셜 광고가 재생 중에 인터스티셜 광고 재생할 수 없음
1037 인터스티셜 로드 실패: 다른 인터스티셜 광고가 재생 중에 인터스티셜 로드할 수 없음.
1055 보상형 동영상 로드 실패: 시간 초과로 로딩 취소
1056 보상형 동영상 로드 실패: 다른 보상형 동영상 재생 중 보상형 동영상 로드 할 수 없음