Android를 위한 BuzzAdPop SDK 개발 시작하기

BuzzAdPop sdk를 안드로이드에 연동하기 위한 문서입니다. BuzzAdPop은 BuzzAd의 광고 상품 중 하나로 쳇헤드(chat heads)를 광고 지면으로 이용해 광고와 컨텐츠를 유저에게 보여줍니다.

SDK를 앱에 연동하기 전, 아래 사항을 먼저 준비해야 합니다.

Buzzvil의 BD 매니저를 통해 전달받은 app_id와 unit_id
Buzzvil 서버로부터 포인트 적립 요청을 받을 수 있는 매체사 API 서버 - 포인트 postback API 연동문서
- Postback 수신 url 세팅 후 Buzzvil BD 매니저에게 전달

Prerequisite

Android Studio 3.2 혹은 그 이상
minSdkVersion 15 혹은 그 이상
compileSdkVersion 29 혹은 그 이상

Index

Step 1: 설치

BuzzAdPop Sdk는 maven 을 통해 다운받으실 수 있습니다. 다음 코드를 build.gradle 에 추가해 주십시오.

repositories {
    maven { url "https://dl.bintray.com/buzzvil/maven/" }
}

dependencies {
    implementation "com.buzzvil:buzzad-benefit-pop:2.3.+"
}

Note: BuzzAdPop은 BuzzAdBenefit SDK 에 통합되어 배포되고 있습니다.

Step 2: BuzzAdPop SDK 초기화

BuzzAdPop은 BuzzAdBenefit SDK에 통합되어 관리되고 있기 때문에 팝을 초기화 하기 위해서 BuzzAdBenefit을 초기화 해주어야 합니다. 팝을 실행하기 전 BuzzAdBenefit.init()을 호출하여 BuzzAdPop SDK 를 초기화 합니다. 이때 팝을 커스텀 할 수 있는 옵션들과 발급받은 unit id, app id 등을 인자로 넘겨주게 됩니다. 자세한 사항은 초기화 페이지를 참고해 주십시오. 초기화 코드는 앱 실행시 한번만 실행하면 됩니다. 아래 코드는 init() 함수를 Application에서 호출해 주는 코드의 예시입니다.

package ...
import ...
import com.buzzvil.buzzad.benefit.BuzzAdBenefit;
import com.buzzvil.buzzad.benefit.BuzzAdBenefitConfig;
import com.buzzvil.buzzad.benefit.presentation.pop.PopConfig;

public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        final PopConfig popConfig = new PopConfig.Builder(getApplicationContext(), "POP_UNIT_ID_HERE")
                .build();
        final BuzzAdBenefitConfig buzzAdBenefitConfig = new BuzzAdBenefitConfig.Builder("BENEFIT_APP_ID_HERE")
                .add(popConfig)
                .build();

        BuzzAdBenefit.init(this, buzzAdBenefitConfig);
    }
}

Step 3: 로그인

광고를 할당받기 위해 반드시 유저 아이디와 타게팅 정보를 설정해 주어야 합니다. 유저가 매체사 앱에 로그인한 시점에 아래와 같이 UserProfile 을 세팅합니다. 설정값 수정 시, 기존 user profile 값을 호출하여 수정 가능합니다.

userId : 매체사 서비스 유저를 unique 하게 구분할 수 있는 식별값
- 매체사 서비스에서 유니크하다고 판단되는 유저에 대하여, userId 값이 복수 개 연동되거나 변경될 가능성이 있을 경우 사전에 BD 매니저와 논의해야 합니다.
- 예: 매체사 앱 삭제 후 재설치 시 userId 값이 변경되는 경우
gender
- UserProfile.Gender.MALE: 남성
- UserProfile.Gender.FEMALE: 여성
birthYear: 출생년도

final UserProfile.Builder builder = new UserProfile.Builder(BuzzAdBenefit.getUserProfile());
final UserProfile userProfile = builder
        .userId("Your_Service_User_ID")
        .gender(UserProfile.Gender.MALE)
        .birthYear(1985)
        .build();
  
BuzzAdBenefit.setUserProfile(userProfile);

로그아웃 시에는 UserProfile을 null로 설정해 주는 작업이 필요합니다.

BuzzAdBenefit.setUserProfile(null);

Step 4: 권한 설정

BuzzAdPop을 연동하려는 앱이 다른 앱 위에 그리기 권한을 이미 가지고 있다면 해당 부분은 넘어가도 됩니다.

Pop을 실행시키기 위해서는 다른 앱 위에 그리기 권한을 획득해야 합니다. 이는 유저가 직접 설정에서 BuzzAdPop을 연동하려는 앱의 다른 앱 위에 그리기 옵션을 활성화 시켜야 합니다. 유저가 해당 옵션을 활성화 시키지 않으면 Pop을 실행할 수 없습니다. BuzzAdPop SDK에서는 BuzzAdPop 클래스를 통해 현재 앱이 해당 권한을 가지고 있는지 확인하고 유저를 설정으로 보내서 이 권한을 활성화 하도록 유도하는 기능을 제공하고 있습니다. 이 부분을 자체적으로 구현한 경우는 다음 스텝으로 넘어 가시면 됩니다.

Pop을 권한 설정을 해 줄 Activity에 BuzzAdPop 클래스를 변수로 추가합니다.
```
private BuzzAdPop buzzAdPop;
```
Activity의 onCreate에서 Pop의 unit id를 이용해 BuzzAdPop의 인스턴스를 만들어 줍니다.
```
this.buzzAdPop = new BuzzAdPop("POP_UNIT_ID");
```

다음은 앱이 필요한 권한이 있는지 확인하고 없다면 권한을 얻도록 유도하는 코드입니다.

public static final int REQUEST_CODE_SHOW_POP = 1024;

public void enablePop() {
    BuzzAdPop buzzAdPop = new BuzzAdPop("POP_UNIT_ID");
    if (buzzAdPop.hasPermission(context)) {
        // Show pop
    } else {
        buzzAdPop.requestPermissionWithDialog((Activity) context,
            new PopOverlayPermissionConfig.Builder(R.string.pop_name)
                .settingsIntent(OverlayPermission.createIntentToRequestOverlayPermission(context))
                .requestCode(REQUEST_CODE_SHOW_POP)
                .build()
        );
    }
}

사용자가 설정에서 다른 앱 위에 그리기 권한을 주고 나면 원래 Activity로 돌아오게 됩니다. 이 때 Intent로 result 값이 넘어오게 되는데 이 값을 읽어서 설정에서 권한을 받았다는 것을 알 수 있습니다.

import static com.buzzvil.lib.buzzsettingsmonitor.SettingsMonitor.KEY_SETTINGS_REQUEST_CODE;
import static com.buzzvil.lib.buzzsettingsmonitor.SettingsMonitor.KEY_SETTINGS_RESULT;

public class MainActivity extends AppCompatActivity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
		
        if (getIntent().getBooleanExtra(KEY_SETTINGS_RESULT, false)
                && getIntent().getIntExtra(KEY_SETTINGS_REQUEST_CODE, 0) == REQUEST_CODE_SHOW_POP) {
            // Permission granted
        }
    }
}

Step 5. 실행

팝을 활성화 하기 위해서buzzAdPop.showPop() 함수를 호출해 줍니다. 한번 활성화 하면 foreground service가 켜지면서 화면을 껐다켤때마다 팝이 지속적으로 화면에 보이게 됩니다. 팝의 원활한 실행을 위해 광고를 미리 로드한 상태에서 BuzzAdPop.showPop()을 실행시킵니다.

BuzzAdPop buzzAdPop = new BuzzAdPop("POP_UNIT_ID");
buzzAdPop.preload(new BuzzAdPop.PopPreloadListener() {
    @Override
    public void onPreloaded(int adsSize, int articlesSize) {
        buzzAdPop.showPop(context, true);
    }

    @Override
    public void onError(AdError error) {
        buzzAdPop.showPop(context, false);
    }
});

Customize

Customize 페이지 에서 CTA Color 변경, 말풍선 (MessagePreview) 기능 등 Customize 가능 한 기능들을 확인할 수 있습니다.

추가 리소스

Github의 샘플

Pop 샘플 앱: Github (Java)
POP 디자인 가이드 문서

Pop 타입 (2.0): Getting Started