1) Android

전면 광고 적용을 위해서는 Tnk 사이트에서 앱 등록 및 Android 프로젝트 상의 SDK 관련 설정이 우선 선행되어야합니다.

[Android Settings] 의 내용을 우선 확인해주세요.

[Incentive Interstitial Ad]

보상형 전면 광고를 띄우는 것은 아래와 같이 간단히 2줄의 코딩만으로 가능합니다.

Incentive Ad Sample

TnkSession.prepareInterstitialAd(this, TnkSession.PPI);

TnkSession.showInterstitialAd(this);

[Non-Incentive Intestitial Ad]

비보상형 전면 광고를 띄우는 것은 아래와 같이 2줄의 코딩만으로 가능합니다.

Non-Incentive Ad Sample

TnkSession.prepareInterstitialAd(this, TnkSession.CPC);

TnkSession.showInterstitialAd(this);

[Cross Interstitial Ad]

타사와 크로스 광고를 진행하기 위해서는 Display Logic 기능을 이용하시면 됩니다.

아래와 같이 prepareInterstitialAd() 호출시 임의의 문자열을 지정하시고 해당 문자열에 대한 로직을 Tnk 사이트에서 크로스 광고로 설정하시어 이용하실 수 있습니다.

Display Logic을 사용하시면 이후 앱 업데이트하지 않아도 Tnk 서버에서 간단하게 보상형, 비보상형, 인하우스, 크로스 광고 등 원하는 형태로 설정하실 수 있습니다.

자세한 내용은 5) Display Logic 을 참고해주세요.

Cross Interstitial Ad with DisplayLogic Sample

TnkSession.prepareInterstitialAd(this, "your_logic_name");

TnkSession.showInterstitialAd(this);

// Tnk 사이트에서 Publishing > 전면광고 로직 선택 후

// 위 코드에서 입력한 "your_logic_name" 명칭으로 광고 로직을 설정합니다.

[Listener 이용하기]

전면광고의 로딩이 완료되거나 사용자가 전면광고 화면을 닫는 경우 해당 이벤트 발생시점에 필요한 로직을 구현하기 위해서

아래의 TnkAdListener 인터페이스를 이용할 수 있습니다.

TnkAdListener Interface

public interface TnkAdListener {

// 사용자가 닫기버튼이나 Back key를 눌러서 광고화면을 닫은 경우

public static final int CLOSE_SIMPLE = 0;

// 사용자가 광고를 클릭해서 화면이 닫히는 경우

public static final int CLOSE_CLICK = 1;

// 종료시 띄워주는 광고화면에서 종료 버튼을 클릭해서 닫은 경우

public static final int CLOSE_EXIT = 2;

public static final int FAIL_NO_AD = -1; // no ad available

public static final int FAIL_NO_IMAGE = -2; // ad image not available

public static final int FAIL_TIMEOUT = -3; // ad arrived after 5 secs.

public static final int FAIL_CANCELED = -4; // ad frequency settings

public static final int FAIL_NOT_PREPARED = -5; // prepare not invoked.

public static final int FAIL_SYSTEM = -9;

/**

* 전면광고 화면 닫힐 때 호출됩니다.

* 화면이 닫히는 이유를 파라메터로 전달해 줍니다.

* @param type

*/

public void onClose(int type);

/**

* 전면광고 화면이 나타나는 시점에 호출됩니다.

*/

public void onShow();

/**

* 전면 광고를 화면에 띄우지 못했을 경우 호출됩니다.

* 시스템 오류나 광고가 없어서 광고를 띄우지 못했을 경우,

* 광고가 늦게 도착(5초 이상) 하여 광고가 뜨지 않은 경우,

* 광고 노출 주기에 따라서 노출이 취소된 경우에 호출됩니다.

*/

public void onFailure(int errCode);

/**

* 전면 광고 prepare() API 호출 후 show() API 호출 전에 광고가 도착하면 호출됩니다.

* 만약 광고 도착 전에 show() API 가 호출된 경우에는 이후 광고가 도착하였을 때 onShow() 가 호출됩니다.

*/

public void onLoad();

}

전면 광고와 관련되어 TnkAdListener에서 발생하는 이벤트의 내용은 같습니다.

• onClose(int type) : 전면 화면이 닫히는 시점에 호출됩니다. 화면이 닫히는 이유가 type 파라메터로 전달됩니다.

  • CLOSE_SIMPLE (0) : 사용자가 전면 화면의 닫기 버튼이나 Back 키를 눌러서 닫은 경우입니다.

  • CLOSE_CLICK (1) : 사용자가 전면 화면의 광고를 클릭하여 해당 광고로 이동하는 경우 입니다.

  • CLOSE_EXIT (2) : 전면 화면에 앱 종료버튼이 있는 경우 사용자가 앱 종료 버튼을 누른 경우입니다. 이 경우 앱을 종료하는 로직을 TnkAdListener 에 구현해야합니다.

• onFailure(int errCode) : 전면 광고를 가져오지 못한 경우 호출이 됩니다. 에러 코드가 errCode 파라메터로 전달됩니다.

  • FAIL_NO_AD (-1) : 제공할 전면광고가 없을 경우 또는 해당 광고앱이 이미 사용자 단말기에 설치되어 있는 경우입니다.

  • FAIL_NO_IMAGE (-2) : 전면 광고를 가져왔으나 전면 이미지 정보가 없는 경우입니다.

  • FAIL_TIMEOUT (-3) : showInterstitialAd() 호출 후 지정된 timeoout시간 (기본값 5초) 이내에 전면광고가 도착하지 않은 경우입니다. 이 경우에는 전면광고를 띄우지 않습니다.

  • FAIL_CANCELED (-4) : prepareInterstitialAd() 호출하였으나 서버에서 설정한 광고 노출 주기를 지나지 않아 취소된 경우입니다.

    • FAIL_NOT_PREPARED (-5) : prepareInterstitialAd()를 호출하지 않고 showInterstitialAd()를 호출한 경우입니다.

  • FAIL_SYSTEM (-9) : 서버 또는 네트워크 오류가 발생한 경우입니다.

• onLoad() : prepareInsterstitialAd() 호출하여 전면광고를 성공적으로 가져온 경우 호출됩니다. 만약 전면광고가 도착하기 전에 showInterstitialAd() 가 호출되었다면 이후 전면광고 도착시 onLoad() 가 호출되지 않고 바로 전면광고가 보여지면서 onShow()가 호출됩니다.

• onShow() : 전면광고가 화면에 나타날 때 호출됩니다.

TnkAdListener는 prepareInterstitialAd() 의 마지막 파라메터로 지정할 수 있습니다.

[Sample #1]

아래의 예시는 TnkAdListener를 사용하여 광고가 로딩되는 시점에 앱의 상태를 판단하여 광고를 띄울지 말지 결정하는 방식의 구현 예시입니다.

TnkAdListener Sample #1

TnkSession.prepareInterstitialAd(this, TnkSession.CPC, new TnkAdListener() {

@Override

public void onClose(int type) {

}

@Override

public void onFailure(int errCode) {

}

@Override

public void onLoad() {

if (isOkToShow) {

TnkSession.showInterstitialAd(MainActivity.this);

}

else {

// now showing

}

}

@Override

public void onShow() {

}

});

[Sample #2]

아래의 예시는 사용자가 Back-key를 눌렀을때 앱 종료여부를 확인하는 Alert 창을 띄우고, 사용자가 '종료' 버튼을 누르면 전면 광고를 노출시키는 방식을 구현한 예시입니다. 광고가 늦게 도착하는 것을 대비하기 위하여 showInterstitialAd() 호출 시 타임아웃 시간(예시에서는 1초)를 지정하는 것도 좋은 방법입니다. 이 경우 광고가 1초 이내에 도착하지 않으년 TnkAdListener의 onFailure() 메소드가 호출되므로 이때에는 앱을 종료시키거나 다른 안내 창을 띄우도록 구현하실 수 있습니다.

TnkAdListener Sample #2

@Override

public void onBackPressed() {

// 종료전 전면광고 불러온다.

TnkSession.prepareInterstitialAd(this, "on_exit");

// 종료 확인 Alert 창을 띄운다.

AlertDialog.Builder alert = new AlertDialog.Builder(this);

alert.setMessage(getResources().getString(R.string.is_exit)); // 종료 하시겠습니까?

alert.setIcon(android.R.drawable.ic_dialog_info);

alert.setCancelable(true);

alert.setPositiveButton(getResources().getString(R.string.yes),

new DialogInterface.OnClickListener() {

@Override

public void onClick(DialogInterface dialog, int which) {

showExitInterstitial(); // '종료' 버튼 클릭시 전면 광고를 띄운다.

}

});

alert.setNegativeButton(getResources().getString(R.string.no),

new DialogInterface.OnClickListener() {

@Override

public void onClick(DialogInterface dialog, int id) {

}

});

alert.show();

}

private void showExitInterstitial() {

TnkSession.showInterstitialAd(this, "on_exit", 1000L, new TnkAdListener() {

@Override

public void onClose(int type) {

MainActivity.this.finish(); // 사용자가 전면광고 화면을 닫으면 앱을 종료한다.

}

@Override

public void onShow() {

}

@Override

public void onFailure(int errCode) {

// 광고가 없거나 주어진 시간 안에 도착하지 않은 경우이다.

MainActivity.this.finish();

}

@Override

public void onLoad() {

}

});

}

[Sample #3]

위 [Sample #2]의 경우 전면광고가 나타나더라도 그 뒤에는 앱이 그대로 살아 있습니다. 그래서 back-key를 누르면 전면광고가 사라지면서 뒤에 있는 앱 화면이 잠시 나타나는 현상이 있을 수 있습니다. 이런 현상을 없애고자 한다면 간단히 전면광고를 띄우기 위한 별도의 Activity를 만들어서 해결할 수 있습니다.

종료시 전면광고 Activity로 띄우기

// back-key 눌림

public void onBackPressed() {

// 종료전 전면광고 불러온다.

TnkSession.prepareInterstitialAd(this, "on_exit");

// 종료 확인 Alert 창을 띄운다.

AlertDialog.Builder alert = new AlertDialog.Builder(this);

alert.setMessage(getResources().getString(R.string.is_exit)); // 종료 하시겠습니까?

alert.setIcon(android.R.drawable.ic_dialog_info);

alert.setCancelable(true);

alert.setPositiveButton("예",

new DialogInterface.OnClickListener() {

@Override

public void onClick(DialogInterface dialog, int which) {

showExitInterstitialActivity(); // '예' 버튼 클릭시 전면 광고를 별도 Activity 로 띄운다.

}

});

alert.setNegativeButton("아니오",

new DialogInterface.OnClickListener() {

public void onClick(DialogInterface dialog, int id) {

}

});

alert.show();

}

// 전면광고를 띄우기 위한 Activity 를 띄운다.

private void showExitInterstitialActivity() {

Intent intent = new Intent(this, ExitAdActivity.class);

startActivity(intent);

finish(); // 현재 화면은 종료

}

// 전면광고 표시용 Activity

public class ExitAdActivity extends Activity {

@Override

public void onCreate(Bundle savedInstanceState) {

super.onCreate(savedInstanceState);

TnkSession.showInterstitialAd(this, "on_exit", new TnkAdListener() {

@Override

public void onClose(int type) {

ExitAdActivity.this.finish();

}

@Override

public void onShow() {

}

@Override

public void onFailure(int errCode) {

finish();

}

@Override

public void onLoad() {

}

});

}

}

<activity android:name=".ExitAdActivity" android:theme="@android:style/Theme.NoTitleBar" android:screenOrientation="portrait"/>

[Sample #4]

아래의 예시는 사용자가 Back-key를 눌렀을때 2-button 형태의 전면 화면이 나타나며 해당 전면 화면에 '앱 종료' 와 '닫기' 버튼이 제공되는 방식을 구현한 예시입니다. 2-button 전면 프레임은 전면 프레임에 2개의 버튼이 제공되는 특수한 형태의 프레임이며 Tnk의 사이트의 전면광고 로직 설정화면에서 프레임을 '2 Button' 설정해야합니다.

앱 종료시 2-Button 전면 프레임 사용하기

// 사전에 전면 광고를 미리 로딩합니다.

TnkSession.prepareInterstitialAd(this, "on_exit”); // "on_exit"는 display logic 입니다. Tnk 사이트에서 설정한 값으로 넣어줍니다.

// 사용자가 앱을 종료(back-key)하는 시점에 전면광고를 띄웁니다.

public void onBackPressed() {

TnkSession.showInterstitialAd(this, "on_exit", new TnkAdListener() {

@Override

public void onClose(int type) {

// 종료버튼 클릭시에 앱을 종료합니다.

if (type == TnkAdListener.CLOSE_EXIT) {

MainActivity.this.finish();

}

}

@Override

public void onShow() {

}

@Override

public void onFailure(int errCode) {

// 광고 로딩 실패시에는 앱을 바로 종료하거나 다른 광고를 띄우는 로직 등을 넣어줍니다.

MainActivity.this.finish();

}

@Override

public void onLoad() {

}

});

}

[Sample #5]

아래의 예시는 Bold/Thin Frame 사용 시 제한적 커스터마이징 기능 구현 예시입니다. 단말기 화면에 프레임이 가득 차서 상단 또는 하단에 빈 영역이 없는 경우 해당 뷰가 표시되지 않습니다. short 타입의 프레임을 사용하시면 대부분의 단말기에 원활히 표시됩니다.

Bold/Thin Frame Sample #5

// 프레임 배경 색상 설정

TnkStyle.AdInterstitial.backgroundColor = 0xff000000; // 검정색

// 프레임 하단 빈 영역에 표시할 뷰 생성

LinearLayout bottomLayout = new LinearLayout(getApplicationContext());

bottomLayout.setLayoutParams(new ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT));

TextView textView = new TextView(getApplicationContext());

textView.setLayoutParams(new ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT));

textView.setPadding(0, 0, 50, 0);

textView.setTextSize(15f);

textView.setTextColor(Color.WHITE);

textView.setGravity(Gravity.RIGHT|Gravity.CENTER_VERTICAL);

textView.setText("뒤로 가기 버튼을 누르면 앱이 종료됩니다.");

bottomLayout.addView(textView);

// 전면 광고 호출

TnkSession.prepareInterstitialAd(MainActivity.this, TnkSession.CPC, null, bottomLayout, new TnkAdListener() {

@Override

public void onClose(int type) {

MainActivity.this.finish();

}

@Override

public void onFailure(int errCode) {

}

@Override

public void onLoad() {

}

@Override

public void onShow() {

}

});

TnkSession.showInterstitialAd(MainActivity.this);

[Interstitial Ad APIs]

전면 광고를 띄우기 위해서 사용하는 prepareInterstitialAd() 와 showInterstitialAd() 의 API 규약은 아래와 같습니다.

- TnkSession.prepareInterstitialAd()

Method

- void TnkSession.prepareInterstitialAd(Activity activity, String displayLogic)

- void TnkSession.prepareInterstitialAd(Activity activity, String displayLogic, TnkAdListener listener)

- void TnkSession.prepareInterstitialAd(Activity activity, String displayLogic, View topView, View bottomView)

- void TnkSession.prepareInterstitialAd(Activity activity, String displayLogic, View topView, View bottomView, TnkAdListener listener)

Description

하나의 전면광고를 로딩합니다. 로딩된 전면광고는 이후 showInterstitialAd() API를 호출하여 화면에 띄울수 있습니다.

반드시 Main UI Thread 상에서 호출하여야 합니다.

Parameters

- TnkSession.showInterstitialAd()

Method

- void TnkSession.showInterstitialAd(Activity activity [, String displayLogic])

- void TnkSession.showInterstitialAd(Activity activity [, String displayLogic], long timeoutMillis)

- void TnkSession.showInterstitialAd(Activity activity [, String displayLogic], TnkAdListener listener)

- void TnkSession.showInterstitialAd(Activity activity [, String displayLogic], long timeoutMillis, TnkAdListener listener)

Description

prepareInterstitialAd()를 통하여 로딩된 전면광고를 화면에 띄웁니다. 정상적으로 광고가 화면에 나타나면 TnkAdListener의 onShow()가 호출되며, showInterstitialAd() 호출 후 지정한 timeoutMillis(기본값 5초) 이내에 광고가 로딩되지 않으면 TnkAdListener 객체의 onFailuer() 가 호출됩니다.

반드시 Main UI Thread 상에서 호출하여야 합니다.

Parameters

[Interstitial Ad Customizing]

전면광고 화면의 종료버튼의 위치와 크기는 개발자가 원하는 형태로 변경이 가능합니다.

- 닫기버튼의 위치

전면광고를 닫기 위하여 화면에 표시되는 닫기버튼(X 버튼)은 기본적으로 우측 상단에 표시됩니다. 이 위치는 좌측이나 하단으로 변경하실 수 있습니다. 전면 광고가 사용되는 Activity의 onCreate() 메소드 내에 아래와 같이 코딩을 넣습니다.

닫기 버튼 위치 변경

TnkStyle.AdInterstitial.closeButtonAlignRight = true; // true(우측), false(좌측)

TnkStyle.AdInterstitial.closeButtonAlignTop = false; // true(상단), false(하단)

2-button 형태의 전면 프레임을 사용하는 경우 '닫기' 버튼 기능은 기본적으로 오른쪽 버튼에서 동작합니다. '닫기' 버튼 기능을 왼쪽 버튼에서 동작하도록 하고 싶으시면 아래와 같이 위치 설정을 하실 수 있습니다. 이 경우 버튼의 라벨도 같이 변경해주셔야합니다.

2-Button 전면 프레임에서 닫기 버튼 위치 변경

TnkStyle.AdInterstitial.closeButtonAlignRight = false; // 닫기 버튼 기능을 왼쪽으로 지정한다.

// 버튼 라벨도 바뀌 버튼의 위치에 맞추어 같이 변경한다.

TnkStyle.AdInterstitial.leftButtonLabel = "닫기";

TnkStyle.AdInterstitial.rightButtonLabel = "App 종료";

- 닫기버튼의 크기

기본적으로 표시되는 닫기버튼의 크기를 키우고 싶은 경우에는 아래와 같이 비율을 지정하시면 닫기버튼의 크기를 변경하실 수 있습니다. 아래의 예시는 크기를 2배로 키우는 에시 입니다.

닫기 버튼의 크기

TnkStyle.AdInterstitial.closeButtonWidthScale = 2.0f;

TnkStyle.AdInterstitial.closeButtonHeightScale = 2.0f;

[Window Mode]

전면광고가 화면에 나타나는 방식은 앱에서 지정한 Activity 또는 View에 광고View 가 Add 되는 방식이 기본적으로 사용됩니다.

대부분의 경우 문제가 없지만 Tab 형태의 화면이나 ViewPager 등을 사용시에는 광고 View가 앱 화면의 일부에 노출이 되거나 다른 화면에 가려지는 현상이 나타날 수 있습니다.

또한 NativeActivity를 사용하는 경우에는 View를 add하는 기능 자체가 동작하지 않기 때문에 광고 View가 화면에 나타나지 않는 문제가 발생합니다.

이런 문제를 해결하기 위하여 Tnk SDK에서는 광고 View를 단말기의 최상단 Window 에 View를 직접 표시할 수 있는 기능을 제공합니다. 이 방식을 사용하면 NativeActivity 에서도 정상적으로 광고 View가 표시됩니다.

Window Mode를 사용하여 전면광고를 표시하고 싶은 경우에는 광고 API 사용전에 아래 코드를 넣어주시면 됩니다. (Unity와 NativeActivity를 사용하는 경우에는 항상 Window Mode 가 자동적으로 적용됩니다.)

Window Mode 사용하기

TnkStyle.AdInterstitial.useWindowMode = true;

[화면 Orientation 처리]

화면 방향을 세로 또는 가로로 고정하지 않은 경우 전면광고가 뜬 상태에서 화면을 회전시 전면광고는 사라지도록 되어 있습니다. 그러나 화면 회전을 자체적으로 코딩하도록 구현하신 경우에는 화면 회전 시점에 전면광고를 닫도록 아래와 같이 코딩을 추가하셔야합니다.

화면 Orientation 처리

1) 해당 Activity에 아래와 같이 configChanges 설정되어 있으면 화면 회전을 자체적으로 처리하는 경우입니다.

AndroidMenifest.xml

<activity android:name=".MainActivity" ...

android:configChanges="orientation|screenSize">

2) 이 경우에는 해당 Activity 에 아래와 같이 코딩이 필요합니다.

@Override

public void onConfigurationChanged(Configuration newConfig) {

super.onConfigurationChanged(newConfig);

TnkSession.removeCurrentInterstitialAd(this);

}