Cocos2d-x SDK 연동 가이드

Adjust Android SDK를 사용하면 Cocos2d-x 앱에서의 어트리뷰션, 이벤트 등을 기록할 수 있습니다. 본 가이드의 단계를 수행하여 Adjust SDK와 연동되도록 앱을 설정하시기 바랍니다.

1. Adjust SDK 설치

Cocos2d-x 앱에서 Adjust SDK를 시작하려면 우선 프로젝트에 Adjust SDK를 추가해야 합니다. GitHub releases 페이지에서 최신 버전을 다운로드합니다. 아카이브를 원하는 디렉토리로 추출합니다.

2. 프로젝트에 SDK 추가

프로젝트에 SDK를 추가하는 방법:

1. Adjust SDK 아카이브 추출

2. dist 디렉토리에서 C++ 파일을 복사하고 Cocos2d-x 프로젝트에 추가합니다.

3. ( Android에만 해당 ): C++ 파일의 경로를 Android.mk 파일의 LOCAL_SRC_FILES 섹션에 추가합니다.

   $(LOCAL_PATH)/../../../Classes/Adjust/AdjustConfig2dx.cpp \
   $(LOCAL_PATH)/../../../Classes/Adjust/AdjustAttribution2dx.cpp \
   $(LOCAL_PATH)/../../../Classes/Adjust/AdjustProxy2dx.cpp \
   $(LOCAL_PATH)/../../../Classes/Adjust/AdjustEvent2dx.cpp \
   $(LOCAL_PATH)/../../../Classes/Adjust/Adjust2dx.cpp \
   $(LOCAL_PATH)/../../../Classes/Adjust/AdjustEventFailure2dx.cpp \
   $(LOCAL_PATH)/../../../Classes/Adjust/AdjustEventSuccess2dx.cpp \
   $(LOCAL_PATH)/../../../Classes/Adjust/AdjustSessionFailure2dx.cpp \
   $(LOCAL_PATH)/../../../Classes/Adjust/AdjustSessionSuccess2dx.cpp \
   $(LOCAL_PATH)/../../../Classes/Adjust/AdjustAppStoreSubscription2dx.cpp \
   $(LOCAL_PATH)/../../../Classes/Adjust/AdjustPlayStoreSubscription2dx.cpp \
   $(LOCAL_PATH)/../../../Classes/Adjust/AdjustThirdPartySharing2dx.cpp \
   $(LOCAL_PATH)/../../../Classes/Adjust/AdjustAdRevenue2dx.cpp
   $(LOCAL_PATH)/../../../Classes/Adjust/AdjustAppStorePurchase2dx.cpp \
   $(LOCAL_PATH)/../../../Classes/Adjust/AdjustPlayStorePurchase2dx.cpp \

3. 프로젝트 설정 업데이트

Adjust SDK가 프로젝트에서 작동하도록 하려면 프로젝트 설정을 업데이트해야 합니다. 이 섹션의 지침을 수행하여

Android 설정

SDK JAR 라이브러리

Java Archive (JAR) 라이브러리는 Android를 타겟팅하는 Cocos2d-x 앱에 필요합니다. JAR 라이브러리를 앱에 연동하려면 압축을 푼 아카이브에서 adjust-android.jar 라이브러리를 프로젝트의 libs 폴더로 복사합니다.

권한 추가

Adjust SDK에 기기 정보에 대한 액세스 권한을 부여하려면 앱에서 요구하는 권한을 선언해야 합니다. 이를 위해 AndroidManifest.xml 파일에 권한을 추가합니다.

온라인 기능에 액세스하려면 다음 권한을 추가하시기 바랍니다.

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

앱이 Google 플레이 스토어를 타겟으로 하지 않는 경우 기기의 네트워크 상태에 액세스하는 다음 권한을 추가합니다.

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>

Adjust SDK에는 com.google.android.gms.AD_ID 권한이 기본값으로 포함됩니다. 앱이 COPPA(Children’s Online Privacy Protection Act, 어린이 온라인 개인정보 보호법) 준수 대상이거나 Google 플레이 스토어를 타겟으로하지 않는 경우 remove를 사용하여 이 권한을 삭제해야 합니다.

<uses-permission android:name="com.google.android.gms.permission.AD_ID" tools:node="remove"/>

Proguard 설정

앱 최적화를 위해 Proguard를 사용하는 경우 Proguard가 클래스를 삭제하는 것을 방지하는 규칙을 추가해야 합니다.

-keep class com.adjust.sdk.** { *; }
-keep class com.google.android.gms.common.ConnectionResult {
   int SUCCESS;
}
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient {
   com.google.android.gms.ads.identifier.AdvertisingIdClient$Info getAdvertisingIdInfo(android.content.Context);
}
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient$Info {
   java.lang.String getId();
   boolean isLimitAdTrackingEnabled();
}
-keep public class com.android.installreferrer.** { *; }

Google 플레이 스토어에서 앱을 게시하지 않는 경우 다음의 규칙을 추가합니다.

-keep public class com.adjust.sdk.** { *; }

설치 리퍼러 설정

설치 리퍼러는 설치를 소스에 어트리뷰션하는 데 사용할 수 있는 고유한 식별자입니다. Adjust SDK는 어트리뷰션을 위해 이 정보가 필요합니다. 다음 메서드 중 하나를 사용하여 설치 리퍼러 정보를 조회하시기 바랍니다.

Google Play Referrer API

Google Play 리퍼러 API는 Google 플레이 스토어를 타겟으로 하는 앱에서 사용할 수 있습니다.

Google Play 리퍼러 API를 지원하려면 build.gradle 파일에 다음을 추가합니다.

dependencies {
   implementation 'com.android.installreferrer:installreferrer:2.2'
}

Proguard를 사용하는 경우 dependency가 삭제되는 것을 방지하는 규칙을 추가해야 합니다.

-keep public class com.android.installreferrer.** { *; }

Huawei 리퍼러 API

Huawei 리퍼러 API는 Huawei 기기를 타겟으로 하는 앱에서 사용할 수 있습니다. Adjust SDK는 Huawei App Gallery v10.4 이상을 사용하는 Huawei 기기에서의 설치를 기록할 수 있습니다. 이 API를 지원하기 위해 필요한 변경 사항은 없습니다.

Meta 설치 리퍼러

Adjust SDK는 v4.36.0 이상 버전에서 Meta 설치 리퍼러 를 지원합니다. 이 기능을 활성화하려면 다음을 수행하시기 바랍니다.

1. 앱 대시보드에서 Meta 앱 ID를 확인합니다. 자세한 내용은 Meta의 앱 대시보드 문서를 참조하시기 바랍니다.

2. Meta 앱을 AndroidManifest.xml 파일에 추가합니다.

   <queries>
      <package android:name="com.facebook.katana" />
   </queries>
   
   <queries>
      <package android:name="com.instagram.android" />
   </queries>

3. 앱 ID를 string 인수로 AdjustConfig2dx.setFbAppId 메서드에 전달합니다.

   AdjustConfig2dx adjustConfig = AdjustConfig2dx(appToken, environment, false);
   adjustConfig.setFbAppId("your-fb-app-id");
   Adjust2dx::start(adjustConfig);

iOS 설정

Adjust SDK는 특정 iOS 프레임워크가 앱에 포함된 경우 추가적인 정보를 얻을 수 있습니다. 이러한 프레임워크는 특정 SDK 기능을 활성화하지만, SDK가 일반적으로 작동하기 위해 반드시 필요한 것은 아닙니다. Project Settings —> Build Phases —> Link Binary With Libraries 에서 프레임워크를 추가한 뒤 이를 ‘optional’로 지정할 수 있습니다.

링커 플래그 추가

AdjustSdk.framework 의 카테고리를 지원하려면 링커 플래그를 추가해야 합니다. 다음을 수행하시기 바랍니다.

1. Project Settings —> Build Settings 로 이동합니다.
2. Other Linker Flags 를 선택합니다.
3. -ObjC 플래그를 추가합니다.

추가 소스 파일 복사

iOS 설정을 완료하려면 Cocos2d-x C++ 파일과 함께 모든 Objective-C++ (.h 및 .mm) 파일을 Xcode 프로젝트에 복사해야 합니다. 모든 .mm 파일이 Build Phases —> Compile Sources 섹션에 나열되는지 확인합니다.

4. Adjust SDK 연동

프로젝트 설정 업데이트가 완료되면 Adjust SDK를 앱에 연동할 수 있습니다. 다음을 수행하시기 바랍니다.

1. Project Navigator 에서 application delegate 파일을 찾아 엽니다.

2. 파일 상단에 Adjust/Adjust2dx.h 클래스를 포함합니다.

3. 다음 인수를 사용하여 applicationDidFinishLaunching 메서드 내에서 AdjustConfig2dx 객체를 인스턴스화합니다.

   • appToken: Adjust 앱 토큰
   • environment: AdjustEnvironmentSandbox2dx

4. 선택적으로 로깅 수준을 조정하여 로깅의 상세도(verbosity)를 조정하시기 바랍니다.

5. 이벤트 인스턴스를 인수로 Adjust2dx::start 메서드를 호출합니다.

#include "Adjust/Adjust2dx.h"

bool AppDelegate::applicationDidFinishLaunching() {
   std::string appToken = "{YourAppToken}";
   std::string environment = AdjustEnvironmentSandbox2dx;

   AdjustConfig2dx adjustConfig = AdjustConfig2dx(appToken, environment);
   adjustConfig.setLogLevel(AdjustLogLevel2dxVerbose);
   Adjust2dx::start(adjustConfig);
}

5. 세션 전송 구성(Android에만 해당)

Adjust SDK가 Android 기기에서 세션 정보를 전송할 수 있도록 하려면 앱이 백그라운드로 전송되거나 포그라운드로 전환될 때 특정 Adjust 메서드를 호출해야 합니다. 이를 구성하려면 다음을 수행하시기 바랍니다.

1. Project Navigator 에서 application delegate 파일을 찾아 엽니다.

2. applicationWillEnterForeground 메서드의 onResume 메서드에 콜을 추가합니다.

3. applicationDidEnterBackground 메서드의 onPause 메서드에 콜을 추가합니다.

   #include "Adjust/Adjust2dx.h"
   
   void AppDelegate::applicationDidEnterBackground() {
      #if (CC_TARGET_PLATFORM == CC_PLATFORM_ANDROID)
         Adjust2dx::onPause();
      #endif
   }
   
   void AppDelegate::applicationWillEnterForeground() {
      #if (CC_TARGET_PLATFORM == CC_PLATFORM_ANDROID)
         Adjust2dx::onResume();
      #endif
   }

6. 앱 빌드

잘하셨습니다! 이제 Flutter 앱을 빌드하고 실행할 수 있습니다. 로깅을 실행하여 문제가 있는지 확인합니다. 로그를 검토하여 Install tracked 메시지를 확인합니다.

Adjust SDK를 통해 사용자 어트리뷰션을 시작할 수 있습니다.