Android

1. 사전 요구 사항

• Android Studio

• Minimum version of Android SDK 24

적용할 SDK 최신 버전은 CHANGELOG.md 파일을 참고해주세요.

2. SDK Integration

2.1 SDK 추가하기

Android Project 의 setting.gradle.kts (Kotlin DSL) 또는 build.gradle (Groovy) 의 repositories 설정에 mavenCentral() 이 추가되어 있는지 확인합니다.

Kotlin DSL

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

Groovy

그리고 App 의 gradle 설정 파일에 다음과 같이 SDK dependency 설정을 추가합니다.

Kotlin DSL

// build.gradle.kts (Module: app)
dependencies {
    implementation("io.snapplay:s2offerwall-aos-sdk:1.0.25")
    // Other dependencies
}

Groovy

2.2 APP ID 설정하기

고객사 페이지에 매체를 생성하여 APP_ID 를 발급 받습니다. 발급 받은 APP_ID 를 AndroidManifest.xml 파일에 등록합니다. 또는 SDK 초기화 전에 별도 API 를 호출하여 APP_ID 를 설정할 수 있습니다.

AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <application ...>
        <activity .../>
            
        <meta-data android:name="s2_app_id" android:value="<YOUR_APP_ID>"/>
    </application>

</manifest>

Java / Kotlin

2.3 SDK 초기화

SDK 사용 전에 초기화 API 를 호출해야합니다. 초기화 결과를 전달 받기 위하여 InitializeListener 인터페이스를 사용할 수 있습니다.

Java

public interface InitializeListener {
    void onSuccess();
    void onFailure();
}

Kotlin

호출 예시

Java

S2Offerwall.initSdk(this, new S2Offerwall.InitializeListener() {
    @Override
    public void onSuccess() {
        bindOfferwallButton(true);
    }

    @Override
    public void onFailure() {
        bindOfferwallButton(false);
    }
});

Kotlin

2.4 사용자 식별값 설정하기

광고 참여를 위해서는 사용자 식별값이 설정되어야합니다. 일반적으로 매체의 로그인 ID 가 사용되며 아래의 API 를 호출하여 SDK 에 사용자 식별값을 설정합니다. 이렇게 설정된 식별값은 이후 사용자가 광고 참여를 완료하는 시점에 매체의 서버로 callback 이 호출되는데 그때 pub_user_nm 파라메터로 전달됩니다.

사용자 식별값의 경우 로그인 ID 를 바로 사용하지 마시고 개인 정보 이슈가 없도록 가급적 Hash 또는 암호화된 값으로 전달해주시기 바랍니다.

Java

// 사용자 식별값을 설정
S2Offerwall.setUserName(Context context, String userName [, String displayName]);

// 설정된 사용자 식별값을 제거
S2Offerwall.resetUserName(Context context);

Kotlin

SDK v1.0.19 부터 setUserName() 에 displayName 파라메터가 추가되었습니다. 해당 파라메터는 오퍼월내 이벤트에서 랭킹 등을 표시할 때 사용되며 유저의 앱 내 닉네임 등으로 전달해주시면 됩니다. Snap 오퍼월의 다양한 이벤트들을 100% 활용하기 위하여 displayName 파라메터가 필요하므로 가급적 적용해주시기 바랍니다.

유저의 닉네임등이 노출되면 안되는 경우에는 원하시는 형태로 마스킹 처리 후 (예: 우리****) 전달해주시기 바랍니다.

3. 오퍼월 띄우기

3.1 EventListener

오퍼월 내에서 발생하는 이벤트를 처리하기 위하여 EventListener 를 구현하여 설정해야합니다. Android의 경우에는 3 종류의 이벤트가 발생할 수 있습니다.

• 사용자가 광고 참여하는 시점에 아직 사용자 식별값이 설정되어 있지 않다면 onLoginRequested() 가 호출됩니다.

• 오퍼월이 닫혀야하는 시점에 onCloseRequested() 가 호출됩니다. 대부분의 경우는 SDK 내부에서 처리되지만 만약 OfferwallView 를 직접 생성하여 화면을 구성한 경우에는 적절한 액션을 수행하도록 구현해야합니다.

• 이미지 첨부가 필요한 광고의 경우 이미지 첨부 시점에 onPermissionRequested() 가 호출됩니다. 이 때에는 일반적으로 Activity 의 requestPermissions() API 를 호출하여 권한 획득을 할 수 있도록 구현합니다.

아래는 EventListener 인터페이스와 그 사용 예시입니다.

Java

public interface EventListener {

    // 오퍼월에서 광고 참여 시점에는 사용자 정보가 필요하다. 이때 매체의 경우 로그인 아이디를 설정한다.
    void onLoginRequested(String param);
    
    // 오퍼월이 닫혀야 할 경우 아래 이벤트가 호출된다. 매체에서는 적절한 액션을 수행하도록 구현한다.
    void onCloseRequested(String param);
    
    // 이용문의 등에서 이미지 파일 첨부 등 실행시 필요한 권한을 요청한다.
    void onPermissionRequested(String permission);
}

Kotlin

아래는 전역 EventListener 를 설정하는 예시입니다.

Java

S2Offerwall.setEventListener(new S2Offerwall.EventListener() {
    @Override
    public void onLoginRequested(String param) {
        S2Offerwall.setUserName(JavaActivity.this, getLoginId());
    }

    @Override
    public void onCloseRequested(String param) {
        //
    }

    @Override
    public void onPermissionRequested(String permission) {
        requestPermissions(new String[]{permission}, PERMISSION_REQ_CODE);
    }
});

Kotlin

3.2 로그인 지연 처리

일반적으로 사용자가 앱에 로그인 하는 시점에 setUserName() 을 호출하여 SDK 에 사용자 식별값을 설정합니다. 하지만 사용자 식별값이 설정되지 않았어도 오퍼월 이용은 가능합니다.

사용자의 적극적인 참여를 위하여 우선 오퍼월을 경험하게 한 후 사용자 식별값이 꼭 필요한 시점 (광고 참여 또는 이용문의)에 로그인을 수행하도록 처리할 수 있습니다. 이를 위하여 EventListener의 onLoginRequest() 를 이용합니다.

onLoginRequest() 가 호출되면 앱의 로그인 페이지로 이동시킨 후 사용자가 로그인을 완료하면 setUserName() 을 호출하여 사용자 식별값을 설정해줍니다. 이후 로그인 페이지를 닫으면 오퍼월로 재진입되어 사용자 액션을 이어서 진행할 수 있습니다.

3.3 S2OfferwallActivity

오퍼월 화면을 별도의 Activity로 제공합니다. S2Offerwall.startActivity() 를 호출하며 파라메터로 표시하고자 하는 오퍼월의 플레이스먼트 이름을 지정해야합니다. 플레이스먼트는 Snapplay 사이트에서 설정할 수 있습니다.

그리고 오퍼월에는 "main" 이라는 이름의 특수한 형태의 오퍼월이 있습니다. 메인 오퍼월은 여러개의 플레이스먼트 오퍼월을 조합하여 하나의 화면에 표시해주는 오퍼월입니다. 메인 오퍼월을 띄우고자 할 때에는 플레이스먼트 이름 대신에 별도로 정의된 S2Offerwall.MAIN 을 지정합니다.

S2OfferwallActivity 는 전역 EventListener 를 설정해야하며 만약 startActivity() 시점에 SDK 초기화가 되어 있지 않았다면 내부에서 먼저 초기화 수행하고 그 이후에 오퍼월을 표시합니다.

아래는 S2OfferwallActivity을 호출하는 예시입니다.

Java

S2Offerwall.startActivity(JavaActivity.this, "your_placement_name");
// or
S2Offerwall.startActivity(JavaActivity.this, S2Offerwall.MAIN);

Kotlin

3.4 S2OfferwallView

오퍼월을 표시하는 View 클래스입니다. 오퍼월을 매체의 특정 영역에 표시하고자 할 경우 사용할 수 있습니다. S2OfferwallView 를 생성하고 원하는 영역에 추가한 후에 EventListener 를 설정하고 이후 load() 함수를 호출하여 원하는 오퍼월을 표시합니다.

아래는 S2OfferwallView 를 사용하는 예시입니다.

Java

// JavaActivity.java

private S2OfferwallView createOfferwallView() {
    S2OfferwallView offerwallView = new S2OfferwallView(this, null);
    ViewGroup.LayoutParams layoutParams = new ViewGroup.LayoutParams(
            ViewGroup.LayoutParams.MATCH_PARENT,
            ViewGroup.LayoutParams.MATCH_PARENT);

    offerwallView.setLayoutParams(layoutParams);

    ViewGroup offerwallLayout = findViewById(R.id.offerwall_layout);
    offerwallLayout.addView(offerwallView);

    offerwallView.setEventListener(new S2Offerwall.EventListener() {
        @Override
        public void onLoginRequested(String param) {
            // ...
        }

        @Override
        public void onCloseRequested(String param) {
            // ...
        }
        
        @Override
        public void onPermissionRequested(String permission) {
            // ...
        }
    });

    return offerwallView;
}

private void loadOfferwall() {
    S2OfferwallView offerwallView = createOfferwallView();
    offerwallView.load("your_placement_name");
}

Kotlin

3.5 개인정보 수집 동의

오퍼월 최초 사용시 개인 정보 수집 동의 다이알로그가 뜨고 여기에서 동의를 해야만 오퍼월로 진입하게 됩니다. S2Offerwall.startActivity() 를 호출하는 경우 내부에서 이에 대한 처리를 진행하지만 만약 S2OfferwallView 를 사용하여 직접 오퍼월 View 를 띄우는 경우에는 개인 정보 수집 동의 다이알로그를 띄우도록 구현을 해야합니다.

아래의 구현 예시를 참고하여 구현합니다.

Java

private void loadOfferwall() {
    S2OfferwallView offerwallView = createOfferwallView();
    S2Offerwall.showConsentDialog(MainActivity.this, () -> {
        // 동의 후 오퍼월 로딩하기
        offerwallView.load("your_placement_name");
    });
}

Kotlin

만약 자체적으로 오퍼월 관련 개인 정보 수집 동의를 받는 경우에는 SDK 가 제공하는 동의 창을 비활성화해야합니다. 아래의 API 를 사용하여 개인 정보 수집동의 창 기능을 on/off 할 수 있습니다.

Java

S2Offerwall.setConsentDialogRequired(Context context, boolean required);

Kotlin

4. Sample Code

아래는 버튼을 클릭하면 S2OfferwallActivity 를 띄우는 가장 간단한 구현 코드입니다.

Java

import android.os.Bundle;
import android.widget.Button;
import androidx.appcompat.app.AppCompatActivity;

import s2.adapi.sdk.offerwall.S2Offerwall;

public class JavaActivity extends AppCompatActivity {

    private static final int PERMISSION_REQ_CODE = 1001;
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        S2Offerwall.setEventListener(new S2Offerwall.EventListener() {
            @Override
            public void onLoginRequested(String param) {
                S2Offerwall.setUserName(JavaActivity.this, getLoginId(), getUserNickname());
            }

            @Override
            public void onCloseRequested(String param) {
                // ...
            }

            @Override
            public void onPermissionRequested(String permission) {
                requestPermissions(new String[]{permission}, PERMISSION_REQ_CODE);
            }
        });

        Button btn = findViewById(R.id.offerwall_btn);
        btn.setOnClickListener(v -> {
            S2Offerwall.startActivity(JavaActivity.this, S2Offerwall.MAIN);
        });
    }

    private String getLoginId() {
        String loginId = "your_login_id"; // implements your own code
        return loginId;
    }
    
    private String getUserNickname() {
        String nickname = "화면 표시용 명칭"; // implements your own code
        return nickname;
    }
}

Kotlin

activity_main.xml

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/main"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <Button
        android:id="@+id/offerwall_btn"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="offerwall"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent" 
    />
    
</androidx.constraintlayout.widget.ConstraintLayout>