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.9.+"
}

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

Step 2: BuzzAdPop SDK 초기화

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

 PopConfig 를 통해 Unit ID 를 설정합니다.

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(getApplicationContext())
                .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 클래스를 통해 현재 앱이 해당 권한을 가지고 있는지 확인하고 유저를 설정으로 보내서 이 권한을 활성화 하도록 유도하는 기능을 제공하고 있습니다. 이 부분을 자체적으로 구현한 경우는 다음 스텝으로 넘어 가시면 됩니다.

1. Pop을 권한 설정을 해 줄 Activity에 BuzzAdPop 클래스를 변수로 추가합니다.
   

   private BuzzAdPop buzzAdPop;

2. Activity의 onCreate에서 Pop의 unit id를 이용해 BuzzAdPop의 인스턴스를 만들어 줍니다.
   

   this.buzzAdPop = new BuzzAdPop(context, "POP_UNIT_ID");

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

   public static final int REQUEST_CODE_SHOW_POP = 1024;
   
   public void showPopOrRequestPermissionWithDialog() {
       BuzzAdPop buzzAdPop = new BuzzAdPop(context, "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()
           );
       }
   }

4. 사용자가 설정에서 다른 앱 위에 그리기 권한을 주고 나면 원래 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.preloadAndShowPop() 함수를 호출해 줍니다. 한 번 활성화 하면 foreground service가 켜지면서 화면을 껐다켤때마다 팝이 지속적으로 화면에 보이게 됩니다.

BuzzAdPop buzzAdPop = new BuzzAdPop(context, "POP_UNIT_ID");
buzzAdPop.preloadAndShowPop(context);

개인정보 취급 방침

개인정보 보호법과 구글 정책에 대응하기 위해, 유저가 버즈빌 광고 지면에 들어갈 때, 개인정보 수집 및 사용에 대한 동의를 받게 됩니다. 별도의 지면 이동 없이, 동일 지면에서 개인정보 사용 정책을 확인할 수 있습니다. 미동의시 버즈빌 제품을 사용할 수 없으며, 유저가 개인정보 수집 및 사용에 대한 동의를 한 이후부터 버즈빌의 유저 데이터 수집 및 광고 참여가 가능합니다.

개인정보 수집 동의는 bottom-sheet 형태로 보여주며, API로 호출 가능합니다.

개인정보 취급 방침과 관련해서 다음과 같은 API를 사용할 수 있습니다.

// 개인정보 취급 방침 UI를 보여주는 API
BuzzAdBenefit.getPrivacyPolicyManager().showContentUI(context, listener);

// 개인정보 취급 방침에 대해 `동의함`을 표시
BuzzAdBenefit.getPrivacyPolicyManager().grantConsent();
// 개인정보 취급 방침에 대해 `동의하지 않음`을 표시
BuzzAdBenefit.getPrivacyPolicyManager().revokeConsent();
// 개인정보 취급 방침에 `동의함` 여부를 확인
BuzzAdBenefit.getPrivacyPolicyManager().isConsentGranted();

(중요) 만약 위 API를 사용하지 않는 경우, 다음과 같은 상황에 Buzzvil의 개인정보 취급 방침에 대한 동의를 받는 UI를 퍼블리셔에서 직접 구현해야합니다.

• 미동의 상태에서 Feed 진입 시

• 미동의 상태에서 Pop Icon 클릭 시

• 그 외, 버즈빌 프로덕트 노출을 동의하는 단계

Customize

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

추가 리소스

Github의 샘플

• Pop 샘플 앱: Github (Java)

• POP 디자인 가이드 문서