해피포인트 연동 가이드

시작하기 전에

요구사항

Android

• minSdkVersion ≥ 21 (Android 5.0 Lollipop)

  • 포인트홈의 모든 기능을 이용하기 위해 최신 버전의 안드로이드 사용을 권장합니다.

• Android Studio ≥ 3.2

  • 최신 버전의 IDE 사용을 권장합니다.

  • Android Studio Flamingo 이상 버전에서 개발되고 있습니다.

• Android gradle plugin ≥ 4.0.1

• Google Play 타겟 API 수준 ≥ compileSdkVersion 33

• Kotlin version 1.8.0

  • SDK는 모두 Kotlin 환경에서 테스트되었습니다.

iOS

• iOS 지원 버전

  • iOS 13 이상

  • XCode 11 이상

• Swift 지원 버전

  • Swift 5.3 이상

---

연동 키 발급하기

CashBlock Android SDK을 연동하려면 연동하려는 앱의 고유 식별자가(AppId/AppSecret) 필요합니다. 연동키는 아바티 영업 담당자([e-mail])를 통해 발급이 가능 합니다. 정식으로 발급된 연동키를 사용해야만 정산이 가능 합니다.

• AppID: CashBlock Android SDK를 연동하는 앱별로 부여하는 고유 식별자입니다.

• AppSecret: CashBlock Android SDK를 연동하는 앱별로 부여하는 고유 식별자의 값을 검증하는 고유값입니다.

테스트 연동키

OS	연동키 유형	테스트 연동키
Android	AppID	dca19cb2e4f14c0895b7bdb4d728c685
	AppSecret	d6edd2574bcf43a9
iOS	AppID	af46ad7d30ea40f88ddf0d76345d89f9
	AppSecret	18f4a1ec94574607

라이브 연동키

OS	연동키 유형	테스트 연동키
Android	AppID	91fa96ba80234b21b6f21757552d2141
	AppSecret	fc3d90ce08ef44a9
iOS	AppID	78d42982598e4f61b60e360a05b5a58b
	AppSecret	027891858ac643c3

---

시작하기

Android

AndroidManifest.xml 설정

빌드 키에 따른 서버 설정을 위해 application 블록 내부에 다음 meta-data 값을 추가해주시기 바랍니다.

    <application
    ...
        <meta-data
            android:name="pointhome.config.host"
            android:value="spc" />
    ...
    </application>

원격 저장소(Repository) 설정

build.gradle(project) 구성 사용 시,

프로젝트 수준의 "build.gradle" 파일에 다음 항목을 추가 합니다.

Groovy

allprojects {
  repositories {
    google()
    mavenCentral()
    maven { url "https://jitpack.io" }
    maven { url "https://dl.buzzvil.com/public/maven" }
    maven { url 'https://artifact.bytedance.com/repository/pangle' }
    maven { url 'https://devrepo.kakao.com/nexus/content/groups/public/' }
    maven { url 'https://dl.cloudsmith.io/public/avatye/Android-CashBlock/maven/' }
    maven { url 'https://dl.cloudsmith.io/public/avatye/Android-PointHome/maven/' }
    maven { url 'https://dl.cloudsmith.io/public/avatye/Android-SPC/maven/' }
    maven {
      url "s3://repo.cauly.net/releases"
      credentials(AwsCredentials) {
        accessKey "AKIAWRZUK5MFKYVSUOLB"
        secretKey "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"
      }
    }
  }
}

settings.gradle 구성 사용 시,

AGP 7.1.0 이상 또는 Android Studio Bumblebee 이상 사용시(settings.gradle 이용시)

Groovy

pluginManagement {
  repositories {
    gradlePluginPortal()
    google()
    mavenCentral()
  }
}
dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    google()
    mavenCentral()
    maven { url "https://jitpack.io" }
    maven { url "https://dl.buzzvil.com/public/maven" }
    maven { url 'https://artifact.bytedance.com/repository/pangle' }
    maven { url 'https://devrepo.kakao.com/nexus/content/groups/public/' }
    maven { url 'https://dl.cloudsmith.io/public/avatye/Android-CashBlock/maven/' }
    maven { url 'https://dl.cloudsmith.io/public/avatye/Android-PointHome/maven/' }
    maven { url 'https://dl.cloudsmith.io/public/avatye/Android-SPC/maven/' }
    maven {
      url "s3://repo.cauly.net/releases"
      credentials(AwsCredentials) {
        accessKey "AKIAWRZUK5MFKYVSUOLB"
        secretKey "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"
      }
    }
  }
}

기본 모듈 적용

1.0.2.26

기본 블록을 앱(모듈) 수준의 "build.gradle" 파일에 설정하세요.

Basement

dependencies {
  implementation 'com.avatye.pointhome-unit-spc:product:{SDK-VERSION}'
}

SDK 초기화

Application을 상속한 클래스의 onCreate()에서 다음과 같이 초기화를 진행해주세요.

SPCInitializer.SPCSDK(
            application = //해당 어플리케이션의 Application,
            appID = "98d4d4c35d594451b21f54718e2bc986",
            appSecret = "17293bec4d454bdf",
            sdkLog = // true or false
        )

PARAMETER NAME	PARAMETER TYPE	DESCRIPTION
application	Application	Android Application
appID	String	앱 고유 식별자
appSecret	String	앱 고유 식별자 검증 키
sdkLog	Boolean	로그 출력 유,무를 설정합니다.

서비스 실행하기

PointHome을 이용할 Activity 클래스의 onCreate()에서 다음과 같이 초기화를 진행해주세요.

pointHomeLayoutBuilder 객체의 실행할 Activity를 전달하여 다음과 같이 초기화 합니다.

전달받은 layoutBuilder 의 launchDashboard() 를 통해 포인트홈을 실행 할 수 있습니다.

class App : Application() {
    
    ...
    
    override fun onCreate() {
        super.onCreate()
        
        val spcBuilder = SPCBuilder()
        var pointHomeBottomBuilder: PointHomeBottomBuilder? = null
        
        spcBuilder.pointHomeLayoutBuilder(
            this,
            object : SPCBuilder.OnBuildListener {
                override fun onBuildCompleted(builder: PointHomeBottomBuilder) {
                    pointHomeBottomBuilder = builder
                }

                override fun onBuildFailed(reason: String) {
                    // 전달받은 Activity에 포인트홈 뷰 초기화가 실패하였습니다.
                    // 관련된 system message 가 노출되며 builder가 생성되지 않습니다.
                }
            })
        
        launcherButton.setOnClickListener {
            pointHomeBottomBuilder?.launchDashboard(userKey = "사용할 UserKey", openListener = object :
                PointHomeBottomBuilder.OpenStateListener {
                override fun openFail(reason: String) {
                    //오픈 에러 메시지가 표시됩니다.
                }
            })
    ...
  }

spcBuilder.pointHomeLayoutBuilder(activity = Application)

PARAMETER NAME	PARAMETER TYPE	DESCRIPTION
application	Application	DashBoard이용할 Activity
OnBuildListener	OnBuildListener	초기화 성공시 : onBuildCompleted 를 통해 PointHomeBottomBuilder 가 반환됩니다. 초기화 실패시 : 전달받은 Activity에 포인트홈 뷰 초기화가 실패하였으며, 빌더 반환대신 시스템 메시지가 반환됩니다. 해당 정보는 onBuildFailed 를 통해 초기화 에러 메시지가 반환됩니다.

layoutBuilder.launchDashboard(userKey = String)

PARAMETER NAME	PARAMETER TYPE	DESCRIPTION
userKey	String	체널링 유저의 UserKey
openListener	OpenStateListener	DashBoard 오픈 실패시 에러 메시지가 반환됩니다

에러 반환 확인

포인트홈 적용중 오류가 발생한 경우 다음과 같이 에러가 반환됩니다.

MESSAGE	DESCRIPTION
네트워크 연결이 원활하지 않습니다.	네트워크 오류 등으로 인해 서버통신에 실패하였습니다.
userKey 가 잘못되었습니다.	DashBoard 오픈 시 userKey 를 전달해야 합니다
초기화중 에러가 발생하였습니다.	포인트홈 초기화 중 오류가 발생하였습니다.
서비스 점검 중입니다	서버점검중 나타나는 메시지입니다.
화면을 불러오지 못했습니다. 잠시 후 다시 시도해주세요	서버와의 통신에서 값을 반환받지 못했습니다.
문제가 발생하였습니다.	서버통신 중, 알수없는 오류가 발생하였습니다.

서비스 설정 오류시 해결 사항

난독화 설정

앱 축소, 난독화 및 최적화 | Android 개발자

해피포인트는 "consumer-rules" 설정을 통해 별도의 설정이 필요하지 않으나, 설정에 문제가 있을 경우 아래 설정을 확인해 주세요.

## PAHHYPOINT
-keep class com.avatye.pointhome.** { *; }
-keep class com.avatye.pointhome.unit.spc.** { *; }


## CASHBLOCK
-keep class com.avatye.cashblock.** { *; }
-keep class com.avatye.cashblock.library.** { *; }


## IGAWORKS
-keep class com.igaworks.ssp.** { *; }
-keep class com.igaworks.ssp.R$*
-dontwarn com.igaworks.ssp.**
-keepclassmembers class com.igaworks.ssp.R$*{
    public static <fields>;
}


## UnityAds
-keep class com.unity3d.ads.** { *; }
-keep class com.unity3d.services.** { *; }


## Vungle
-dontwarn com.vungle.warren.downloader.DownloadRequestMediator$Status
-dontwarn com.vungle.warren.error.VungleError$ErrorCode
-dontwarn com.google.android.gms.common.GoogleApiAvailabilityLight
-dontwarn com.google.android.gms.ads.identifier.AdvertisingIdClient
-dontwarn com.google.android.gms.ads.identifier.AdvertisingIdClient$Info
-keep class com.moat.** { *; }
-dontwarn com.moat.**
-keepattributes *Annotation*
-keepattributes Signature
# Prevent R8 from leaving Data object members always null
-keepclassmembers,allowobfuscation class * {
  @com.google.gson.annotations.SerializedName <fields>;
}
-dontwarn javax.annotation.**
-keepnames class okhttp3.internal.publicsuffix.PublicSuffixDatabase
-dontwarn org.codehaus.mojo.animal_sniffer.*
-dontwarn okhttp3.internal.platform.ConscryptPlatform


## Pangle
-keep class com.bytedance.sdk.** { *; }
-keep class com.pgl.sys.ces.* { *; }


## Fan
-keep class com.facebook.ads.** { *; }


## Mobon
-dontwarn com.httpmodule.**
-dontwarn com.imgmodule.**
-keep class com.httpmodule.** { *; }
-keep class com.imgmodule.** { *; }
-keep public class com.mobon.**{
    public *;
}


# Dontwarn
-dontwarn com.adcolony.**
-dontwarn com.bytedance.**
-dontwarn com.mopub.**
-dontwarn com.mintegral.**
-dontwarn com.unity3d.**
-dontwarn com.adobe.**
-dontwarn com.fyber.**
-dontwarn org.chromium.**
-dontwarn com.fsn.cauly.**
-dontwarn com.tapjoy.**

Manifest 충돌

서비스 적용 과정에서 Manifest의 Theme 충돌시 application 블록에 다음과 같이 tools:replace="android:theme" 구문을 추가해 주시기 바랍니다.

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

<application
        android:name=".App"
        ...
        tools:replace="android:theme"
        ...
        >
        <activity
            android:name=".MainActivity"
            android:exported="true">

애드캐시 베너 적용

포인트홈 객체를 통해 애드캐시 서비스를 이용할수 있습니다.

다음 구문을 추가해 주시기 바랍니다.

<?xml version="1.0" encoding="utf-8"?>

---

iOS

설치하기 ( Pod )

PointHome iOS SDK는 CocoaPods 대신 cloudsmith의 pod repository를 사용합니다.

PointHome의 repository를 반드시 추가해주세요.

현재 버전 1.4.3

source 'https://github.com/CocoaPods/Specs.git'
source 'https://dl.cloudsmith.io/public/avatye/ios-sdk/cocoapods/index.git'
target 'MyApp' do
  pod 'PointHome', '~> {SDK-VERSION}'
end

ATS (App Transport Security) 설정

iOS 9 이후부터 도입된 App Transport Security는 앱이 HTTPS를 통해서만 네트워크 요청을 하도록 기본설정이 되어있습니다.

HTTP를 사용하는 광고 파트너들의 광고 동작을 허용하기 위해, Info.plist 파일에 아래 내용을 추가합니다.

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

IDFA 수집 동의 설정

IDFA에 엑세스 하기 위한 앱 추적 투명성 승인 요청을 표시하려면 Info.plist를 업데이트 하여 사용을 설명하는 맞춤 메세지와 함께 NSUserTrackingUsageDescription 키를 추가합니다.

SDK 초기화

AppDelegate에서 다음과 같이 PointHome 초기화를 진행해주세요.

PointHome.setting(appId: "Test_appID",
                  appSecretKey: "Test_appSecretKey",
                  logLevel: .info //optional )

PARAMETER NAME	PARAMETER TYPE	DESCRIPTION
appId	String	앱 고유 식별자
appSecretKey	String	앱 고유 식별자 검증 키
logLevel	Enum	SDK에서 노출하는 로그의 수준을 설정할 수있습니다. (기본값 = .info) .debug : 모든 로그를 노출합니다. .info : 가장 기본적인 로그를 노출합니다. ( Default ) .error : error 로그만 노출합니다.

서비스 실행하기

PointHome을 이용할 클래스에 아래와 같이 실행코드를 추가해주세요.

@IBAction func phBtnAction(_ sender: Any) {
    PointHome.openService(rootVC: self, userKey: 'USER_KEY') { result in
      switch result {
      case .success(let data):
          // 성공시
          print("success \(data)")
      case .failure(let error):
          // 실패시
          print("failure \(error)")
      } 
    }
}

PARAMETER NAME	PARAMETER TYPE	DESCRIPTION
rootVC	ViewController	서비스가 띄워질 ViewController
userKey	String	체널링 유저의 UserKey
(@completion)result	Enum	성공 및 응답 처리를 위한 completion입니다.

---

Web

NAM 및 Feed Web 연동을 위한 Web SDK 설치방법입니다.

자세한 내용은 각 기능의 Web 연동가이드 부분을 참고해주세요.

JS SDK 설치하기

<Html>
    <Head>
    </Head>
    <body>
        // 상용
        <script src={'https://avatye-resources.s3.ap-northeast-2.amazonaws.com/pointhome/webSdk/spc/pointhome-{version}.min.js'} />
        // 테스트
        <script src={'https://avatye-resources.s3.ap-northeast-2.amazonaws.com/pointhome/webSdk/spc/pointhome-{version}-test.min.js'} />
    </body>
</Html>

• 현재 버전: 1.0.4

• script 태그를 <body> 태그 내부의 하단에 추가합니다.

• 대역별로 파일명을 구분하여 작성합니다.

  • 상용: pointhome-1.0.4.min.js

  • 테스트: pointhome-1.0.4-test.min.js

스크립트의 URL이 v1.0.4부터 변경되었습니다.

https://avatye-resources.s3.ap-northeast-2.amazonaws.com/pointhome/webSdk/spc/pointhome-1.0.4.min.js

(이전 레거시 파일(v1.0.4 미만)들은 기존 경로에서도 import 가능합니다.)

Native 연동

Web SDK의 기능 사용을 위해 Native Webview에 Message Handler를 설정해야 합니다.

설정방법은 각 기능별 설치하기 가이드를 참고해주세요.

---

에러

에러 목록

CODE	TYPE	MESSAGE
1000	EXCEPTION	문제가 발생하였습니다
2000	INVALID_USERKEY	userKey가 잘못되었습니다.
9002	NETWORK_ERROR	네트워크 연결이 원활하지 않습니다.
5000	SERVER_ERROR	화면을 불러오지 못했습니다. 잠시 후 다시 시도해주세요.
5003	IN_MAINTENANCE	서비스 점검 중입니다.

---

광고

NAM(Naver Ad Manager)

• Android

• iOS

• Web

Feed Native API

• Android

• iOS

• Web

---

문제 해결

iOS 문제 해결

설치가 안되는 경우

Pod Repo 추가

PointHome은 Pod repo로 cloudsmith를 사용중입니다. 따라서 아래와 같이 기본 pod repo외에 cloudsmith의 repository를 직접 추가해 줘야 합니다.

source 'https://github.com/CocoaPods/Specs.git'
source 'https://dl.cloudsmith.io/public/avatye/ios-sdk/cocoapods/index.git'

target 'MyApp' do
  pod 'PointHome', '~> {SDK-VERSION}'
end

빌드가 안되는 경우

Info.plist 업데이트

PointHome(v1.0.0)의 경우 원활한 광고 테스트를 위해 지원가능한 모든 광고 미디에이션이 추가되어 있습니다. 따라서 기본적으로 포함되어야 하는 키를 Info.plist에 설정해야 합니다. 미디에이션에 관련된 자세한 내용은 애드캐시 가이드의 미디에이션 연동을 참고해주세요

AppLovin

아래 키는 개발용 키이며, 라이브 시에는 아바티로부터 발급받은 키를 사용해야합니다.

<key>AppLovinSdkKey</key>
<string>nPNmWdnX7aDsJQd7yPG7w-rzdTAJJ3qcBNpgSoWzDrm4bUMSmHZJsv-2XRTSiOItVTm7FWZ7PrkUEKeVvlomd1</string>