친구추천

본 문서는 BuzzScreen 유저에 대해 친구추천 기능을 제공하고 추천인과 피추천인에게 포인트를 지급할 수 있는 모듈에 대한 연동 가이드입니다. 본 모듈을 사용하여 친구추천 이벤트를 통해 신규 유저의 유입을 증대시킬 수 있습니다.

Index

1 Getting Started
- 1.1 1. Requirements
- 1.2 2. Prerequisites
2 Basic Usage
- 2.1 1. build.gradle 설정
- 2.2 2. 메소드 호출
  - 2.2.1 1) 친구추천 이벤트 및 유저의 참여 상태 확인
  - 2.2.2 2) 추천인 코드 전달 및 포인트 적립
3 Advanced Usage
- 3.1 앱 다운로드 링크에 referrer paramter로 전달된 추천인 코드 받아오기
  - 3.1.1 1) AndroidManifest.xml 설정
  - 3.1.2 2) BroadcastReceiver 구현
  - 3.1.3 3) 추천인 코드 받아오기

Getting Started

1. Requirements

	항목	세부내용

	항목	세부내용
1	BuzzScreen SDK 버전	1.9.2.3 버전 이상부터 사용 가능
2	친구추천 기능 오픈 대상	잠금화면 사용 이후부터 BuzzScreen의 유저 로 인식되므로, 현재 잠금화면을 사용 중인 유저에 대해서만 오픈하는 것을 권장
3	추천 / 피추천 가능 횟수	유저 1명 당 피추천: 최대 1회 가능 (타인에게) 추천: 복수 회 가능

2. Prerequisites

연동 시작 전, 아래 사항을 버즈빌 BD 매니저에게 전달합니다.

	항목	세부내용

	항목	세부내용
1	친구추천 이벤트 시작 일시	-
2	추천인 & 피추천인에게 지급할 포인트 금액	-
3	Verification url	친구추천 이벤트에 참여하는 유저에 대해 유효한 `user_id` 인지 검증하기 위함 → 관련 API 문서를 참고하여 Endpoint url을 버즈빌에 전달

Basic Usage

1. `build.gradle` 설정

모듈 내 build.gradle 파일에 아래와 같이 친구추천 라이브러리를 연동합니다.

dependencies {
    implementation 'com.buzzvil.buzzscreen.ext:referral:1.0.4'
}

2. 메소드 호출

ReferralHelper라는 클래스 안에 아래와 같은 함수들을 제공하고 있습니다.

1) 친구추천 이벤트 및 유저의 참여 상태 확인

void callUser(Context context, UserResponseListener listener) : 버즈빌 서버로부터 친구추천 이벤트의 진행 상황 및 현재 잠금화면을 사용하고 있는 유저의 친구추천 참여 상태값을 받아옵니다.
- 호출 위치: 추천인 코드를 입력하는 화면의 액티비티를 띄우기 전
- Parameters
  - Context : Application context를 this로 전달
  - UserResponseListener
- Response : 아래 표 참고

콜백	파라미터	세부내용

콜백	파라미터	세부내용
`onSuccess(boolean referralEnabled, String code, int reward, boolean hasDone, boolean eventEnded)` 성공 시 리턴되는 콜백 버즈빌 서버에 설정된 상태에 따라 다른 값이 전달됨	`boolean referralEnabled`	버즈빌 서버에서 친구추천 이벤트로 포인트를 지급할 수 있는 상태인지 여부
	`String code`	해당 유저의 추천인 코드 버즈빌 서버에 유저로 기록되기 위해서는 잠금화면 사용이 필수이므로 잠금화면 활성화 이후에 함수 호출 필요!
	`int reward`	버즈빌 서버에 설정된, 추천인과 피추천인 모두에게 지급될 포인트 금액
	`boolean hasDone`	해당 유저가 추천인 코드를 입력한 적이 있는지 여부. 추천인 코드를 입력하고 포인트를 받아간 이력이 있으면 `True`를 리턴함
	`boolean eventEnded`	이벤트 종료 시점이 지났는지 여부. 이벤트 종료 시점이 지났을 경우 `True`를 리턴함
`onNetworkError(String errorMessage)` 네트워크 에러 시 리턴되는 콜백	`String errorMessage`	모듈에서 제공하는 기본 에러 메시지 `“네트워크 오류 : 다시 시도해주세요”`

참고) Response 값에 따른 UI 구현 사항

친구에게 공유할 앱 다운로드 등의 링크는 아래 항목과 무관하게 상시 사용 가능합니다. 단, 해당 링크에 유저의 추천인 코드를 포함할지 여부는 아래 표를 참고해주세요.

No	`referralEnabled`	`eventEnded`	`hasDone`	추천인 코드 입력란 노출 여부	안내 문구 및 초대 메시지에 포인트 관련 내용 노출	유저 본인의 추천인 코드 노출	공유 링크에 추천인 코드 파라미터 포함*

No	`referralEnabled`	`eventEnded`	`hasDone`	추천인 코드 입력란 노출 여부	안내 문구 및 초대 메시지에 포인트 관련 내용 노출	유저 본인의 추천인 코드 노출	공유 링크에 추천인 코드 파라미터 포함*
1	True	True	True	X	X	X	X
2	True	True	False	△**	X	X	X
3	True	False	True	X	O	O	O
4	True	False	False	O	O	O	O
5	False	-	-	X	X	X	X

*아래 Advanced Usage 내용 참고
**이벤트 종료 전에 포인트 내용이 담긴 초대 메시지를 받은 유저가, 이벤트 종료 후에 추천인 코드 입력 페이지에 접속할 경우 포인트를 지급할 것인지 여부에 따라 입력란 노출 여부를 결정합니다.

2) 추천인 코드 전달 및 포인트 적립

유저가 추천인 코드를 입력하여 제출하는 단계에 아래 메소드를 호출합니다.

유저가 추천인 코드 입력란에 본인의 추천인 코드를 입력하는 경우는 callReferral() 호출 전에 UI 단에서 막는 것을 권장합니다.

void callReferral(Context context, String referrerCode, ReferralResponseListener listener) : 입력된 추천인 코드를 버즈빌 서버에 전달합니다. 전달된 추천인 코드에 따라 해당되는 콜백이 리턴됩니다.
- Context : Application context를 this로 전달
- String referrerCode : 입력된 추천인 코드를 String으로 전달
- ReferralResponseListener
Response : 아래 표 참고

콜백	세부내용

콜백

세부내용

onSuccess()

적립 성공 시 리턴되는 콜백

포인트 적립 요청은 매체사 포인트 적립 포스트백 API 연동 연동 시 버즈빌에 전달한 postback url로 전달됨
이 때 해당 포스트백의 action_type 값
- 추천인: g (give)
- 피추천인: a (accept)

onFail()

적립 실패 시 콜백

두 유저가 서로를 추천하는 경우 (예: 유저 A가 유저 B의 추천인 코드로 포인트를 이미 적립받았는데 유저 B가 유저 A의 추천인 코드로 적립 시도할 경우)
입력된 추천인 코드가 피추천인과 동일할 경우, 즉 유저가 자기자신을 추천할 경우
이 외에 유효한 추천인 코드가 아닐 경우

onNetworkError(String errorMessage)

네트워크 에러 시 리턴되는 콜백

String errorMessage : 모듈에서 제공하는 기본 에러 메시지
- “네트워크 오류 : 다시 시도해주세요”

Advanced Usage

앱 다운로드 링크에 referrer paramter로 전달된 추천인 코드 받아오기

추천인이 피추천인에게 공유하게 될 앱 다운로드 링크 등에 referrer parameter로 추천인 코드가 붙어서 넘어가는 경우, 아래 방법을 통해 자동으로 추천인 코드를 받아올 수 있습니다. 추천인의 링크를 타고 들어온 피추천인이 별도로 추천인 코드를 입력하지 않고 보다 쉽게 포인트를 받아갈 수 있도록 도움을 주기 위해 추가된 함수입니다.

1) `AndroidManifest.xml` 설정

<receiver
   android:name=".ReferrerReceiver"
   android:exported="true">
   <intent-filter>
       <action android:name="com.android.vending.INSTALL_REFERRER" />
   </intent-filter>
</receiver>

2) `BroadcastReceiver` 구현

public class ReferrerReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        // BuzzScreen Referral

        // 기존에 com.android.vending.INSTALL_REFERRER intent를 받아 처리하는 receiver가 존재할 경우, 
        // 해당 Receiver class의 `onReceive()`에 아래 코드를 추가
        new com.buzzvil.buzzscreen.referral.ReferrerReceiver().onReceive(context, intent);
    }
}

3) 추천인 코드 받아오기

String getReferrerCode()