04/28/2025 20:45:30

연동 가이드（Android）

[info]버전 주의사항
minSdkVersion : 15
targetSdkVersion : 28

1 프로젝트 환경설정

1.1 파일 작성

1.2 AndroidManifest 환경설정

<!--TDM begin-->
<!-- 네트워크 통신-->
<uses-permission android:name="android.permission.INTERNET" />
<!-- 네트워크 상태 획득 -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!-- MAC 주소 획득-->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<!--TDM end-->

<application>
    <!-- TDataMaster 환경설정 -->
    <meta-data android:name="GCloud.TDM.AppId" android:value="@string/tdm_AppId" />
    <meta-data android:name="GCloud.TDM.AppChannel" android:value="@string/tdm_AppChannel" />
    <meta-data android:name="GCloud.TDM.Protocol" android:value="@string/tdm_Protocol" />
    <meta-data android:name="GCloud.TDM.Test" android:value="true"/>
</application>

TDM 컴포넌트 접속 시 주의가 필요하므로, TDataMaster 설정 설명과 관련해서 TDM 채널 파일 참조하십시오.

2 프레임워크 실행 예제

2.1 초기화

MSDKPlatform.initialize(this);

2.2 생명주기 함수에 코드 심기

onActivityResult,onNewIntent 와 onRequestPermissionsResult 에 코드 심기
Activity 의 기타 주기 함수는 자체적으로 hook되므로, 별도 처리 필요 없음

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
   super.onActivityResult(requestCode, resultCode, data);
   MSDKPlatform.onActivityResult(requestCode, resultCode, data);
 }

@Override
protected void onNewIntent(Intent intent) {
   super.onNewIntent(intent);
   MSDKPlatform.onNewIntent(intent);
 }

@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {
   super.onRequestPermissionsResult(requestCode, permissions, grantResults);
   MSDKPlatform.onRequestPermissionsResult(requestCode, permissions, grantResults);
 }

2.3 C++ 연동（선택）

헤더파일을 프로젝트/app/src/main/cpp 폴더로 이동：

CMakeLists.txt 에 .so 파일을 아래와 같이 삽입：

ADD_LIBRARY(libMSDKCore.so SHARE IMPORTED)
SET_TARGET_PROPERTIES(
    libMSDKCore.so
    PROPERTIES IMPORTED_LOCATION
    ${CMAKE_CURRENT_SOURCE_DIR}/libs/${ANDROID_ABI}/libMSDKCore.so
)

[warning] 제3자 라이브러리 libThird.so 로 libMSDKCore.so 의 인터페이스를 사용하려고 하는 경우, MSDK 초기화가 필요합니다

그렇지 않으면 undefined linked 오류가 생성될 수 있으므로, 올바른 방법은 아래와 같습니다：

MSDKPlatform.initialize(this);
System.loadLibrary("Third");

2.4 초기화

activity를 실행하여 MSDKPlatform.initialize()를 호출한 뒤 MSDK SDK초기화

  @Override
  protected void onCreate(@Nullable Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      ...
      // 모든 초기화 입구는 이곳에 둔다
      MSDKPlatform.initialize(this);
      ...
    }

2.5 콜백 리스너 생성

로그인 한 경우, MSDKLoginObserver 인터페이스를 활용하여 콜백 리스너를 생성할 수 있으며, 방법은 아래와 같습니다：

private class LoginObserver implements MSDKLoginObserver{

        @Override
        public void onBaseRetNotify(MSDKRet baseRet) {
            MSDKLog.d("onBaseRetNotify, result = " + formatString(baseRet));
            handleLoginResult(baseRet);
        }

        @Override
        public void onLoginRetNotify(MSDKLoginRet loginRet) {
            MSDKLog.d("onLoginRetNotify, result = " + formatString(loginRet));
            handleLoginResult(loginRet);
        }
        private void handleLoginResult(MSDKRet baseRet){
            switch (baseRet.retCode) {
                case MSDKErrorCode.SUCCESS:
                    showResult("로그인 성공", formatString(baseRet));
                    break;
                case MSDKErrorCode.LOGIN_ACCOUNT_REFRESH:
                    showResult("다른 계정：URL을 통해 청구서 새로고침", formatString(baseRet));
                    break;
                case MSDKErrorCode.LOGIN_URL_USER_LOGIN:
                    showResult("다른 계정：URL로 로그인 성공", formatString(baseRet));
                    break;
                case MSDKErrorCode.LOGIN_NEED_SELECT_ACCOUNT:
                    showDiffLogin();
                    break;
                case MSDKErrorCode.LOGIN_NEED_LOGIN:
                    showResult("다른 계정：로그인 페이지 접속해야 함", formatString(baseRet));
                    break;
                case MSDKErrorCode.NEED_NAME_AUTH:
                    // 실명인증
                    break;
                default:
                    showResult("로그인 알림（알 수 없는 메시지）", formatString(baseRet));
                    break;
            }
        }
    }

로그인 성공의 경우 SUCCESS, 실패한 경우 실패 해당 에러코드를 발송하므로 상황에 맞춰 처리가 가능합니다.

2.6 콜백 리스너 설정

MSDKLogin 타입의 setLoginObserver를 통해 리스너 설정이 가능하며, 활용 예는 아래와 같습니다：

//init observer
MSDKLogin.setLoginObserver(new LoginObserver());

2.7 API인터페이스 호출

MSDK인터페이스는 모듈 별로 구분되어 있으므로 호출하기 전, 로그인/ 친구/WebView 등 해당 모듈을 찾아 주십시오. 로그인 상태에서의 호출 방법은 아래와 같습니다：

//채널에 따라 로그인 채널 설정
permissions = getChannelTestPermissions(mSelectedChannel);
//mSelectedChannel채널 로그인
MSDKPlatform.Login.login(permissions, mSelectedChannel, mSelectedSubChannel, "");

주의：

• 모듈마다 각각의 Observer가 있으며，리턴코드가 달라도 유사하게 호출될 수 있습니다
• 하나의 모듈에는 하나의 Observer뿐이며, 여러 번의 설정 후, 최종 설정한 것으로 적용됩니다
• 다른 계정으로 모듈에 로그인하여 Observer를 설정하는 경우, 입구 Activity의 onCreate와 onResume 생명주기 범위내로 설정해야 합니다

3 MSDKPolicy 연동

3.1 개요

MSDKPolicy 는 사용자의 프라이버시 프로토콜과 권한 부여 프로세스를 통합한 범용 Android 데이터 권한 규율 구현 방안으로, 설정 형식을 통해 업무에 빠르게 접근할 수 있습니다.

MSDKPolicy 의 순서도는 다음과 같습니다：

3.2 연동 절차

3.2.1 관련 문서

• msdk_policy_content.html
  프로토콜 내용을 설정하는 데 사용되며, 법무 심의를 거친 문건을 제공드렸습니다

• msdk_permission_content.html
  App 설정을 위해 필요한 권한 리스트와 용도에 대한 설명으로, 현재 콘텐츠는 Demo용이며, App 상황에 맞춰 수정되어야 합니다. 필요한 권한은 앞쪽으로 옮겨 （필요） 구문을 강조해야 합니다

• msdk_permission_list.xml
  필요한 권한을 설정하기 위해 사용되며, 권한으로 순서 폴링을 신청할 수 있습니다. 폴링 과정에서 사용자에게 필요 권한 신청을 요구할 수 있습니다

3.2.2 설정 가이드

（1）MSDKPolicy 불러오기

중요：AndroidManifest.xml 에서 아래 설정을 추가하여, MSDKPolicy 불러오기가 가능합니다

<activity 
    android:name="com.tencent.gcloud.msdk.core.policy.MSDKPolicyActivity"
    android:configChanges ="keyboard|keyboardHidden|screenLayout|screenSize"
    android:launchMode="singleTask"
    android:theme="@style/MSDKPolicyTheme">
    <!-- MSDKPolicy 를 메인 activity로 설정한 뒤 작동 -->
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
        <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
    </intent-filter>
    <!-- MSDK_POLICY_TARGET_ACTIVITY 는 건너뛰기 로 지정할 것에에 사용됨（애플리케이션 또는 게임의 첫 activity）-->
    <meta-data android:name="MSDK_POLICY_TARGET_ACTIVITY" android:value="{your_main_acitivity}" />
    <!-- MSDKPolicy 의 Debug 를 실행하여, 사용자가 로그 출력 호출 -->
    <meta-data android:name="MSDK_POLICY_DEBUG" android:value="true"/>
    <!-- 기본 설정으로, 수정할 필요 없음 -->
    <meta-data android:name="MSDK_RESULT_FILE_NAME" android:value="itop_login.txt"/>
</activity>

중요：위의 설정을 추가한 뒤, 게임에서 mainactivity 의 LAUNCHER 와 MAIN 마크를 삭제해야 합니다

<activity
    android:name=".StartupActivity"
    android:configChanges="orientation|screenSize|keyboardHidden"
    android:launchMode="singleTask"
    android:taskAffinity="com.tencent.itop.example">
    <!-- 더이상 첫 번째 activity 로 실행되는 것이 아니므로, intent-filter 에서 MAIN 과 LAUNCHER 가 주석 처리됨 -->
    <!-- <intent-filter>-->
    <!-- <action android:name="android.intent.action.MAIN" />-->
    <!-- <category android:name="android.intent.category.LAUNCHER"/>-->
    <!-- <category android:name="android.intent.category.LEANBACK_LAUNCHER" />-->
    <!-- </intent-filter>-->
</activity>

（2）MSDKPolicy는 두 부분으로 나뉨

사용자 개인정보 프로토콜：

사용자가 App 아이콘을 클릭해 게임을 시작하면, 사용자 개인정보 프로토콜(위 그림 참조)이 소환됩니다. 그림 속 프로토콜 내용은 설정이 가능하며, 현재 제공되는 버전은 임의 프로토콜로 수정이 필요한 경우, 법무부서에 리스크 평가를 확인한 후 사용하십시오. 프로토콜 내용은 리소스파일 msdk_policy_content.html 에서 설정할 수 있으며, 기본 html 태그만 지원됩니다.

<!doctype html>

<head>
    <meta charset='UTF-8'>
    <meta name='viewport' content='width=device-width initial-scale=1'>
    <title></title>
</head>

<body>
<p>저희(텐센트) 서비스를 이용하시기 전에, <a href='http://game.qq.com/contract.shtml'> 텐센트 게임 라이선스 및 서비스 협약</a>, <a href='http://game.qq.com/privacy_guide.shtml'> 텐센트 게임 개인정보 보호 가이드 </a>와 <a href='https://game.qq.com/privacy_guide_children.shtml'> 텐센트 게임 아동 개인정보 보호 가이드 </a> 의 각 조항을 반드시 주의 깊게 읽어 보시고, 사용자의 개인정보 취급 규칙을 충분히 이해하시길 바랍니다. <strong>아울러, 귀하는 약정에서의 저희측 면책 또는 제한되는 조항과, 사용자의 권리를 제한하는 조항, 분쟁 해결 방식과 사법관할을 약속하는 약정과 관련하여 충분히 확인하시길 바랍니다. </strong>이미 <a href='http://game.qq.com/contract.shtml'> 텐센트 게임 라이선스 및 서비스 협약</a>, <a href='http://game.qq.com/privacy_guide.shtml'> 텐센트 게임 개인정보 보호 가이드 </a>와 <a href='https://game.qq.com/privacy_guide_children.shtml'> 텐센트 게임 아동 개인정보 보호 가이드</a>에 대해 자세히 읽어보셨다면, “동의”를 클릭하여 저희 서비스를 시작하십시오.</p>
</body>

</html>

필요 권한 요청 프로세스：

사용자가 동의를 클릭하면 권한 요청 페이지로 들어가 아래 그림과 같은 필요 권한 요청 프로세스가 시작됩니다.

권한 요청 페이지에 있는 내용은 설정이 가능하며, 실무자는 App에 대한 모든 권한을 정리하여 설정에 추가하면 됩니다. 그 중 필요 권한은 위의 화면 내용과 같이 표시해야 합니다. 설정 파일은 msdk_permission_content.html 로, 기본 html 태그만 지원됩니다.

<p>사용자의 원활한 게임 체험을 위해 사용자가 서비스를 이용하는 과정에서 다음과 같은 권한 수락을 요청할 것이며, 사용자가 해당 권한의 개시를 동의하거나 거부할 경우, 일부 기능에 영향을 줄 수 있습니다：</p>
<br/>
<p><strong>저장 권한（필수）</strong></p>
<p>사진/영상 캐시 저장으로 데이터 소모 줄임</p>
<br/>
<p><strong>단말기/전화 권한（필수）</strong></p>
<p>IMEI&IMSI 코드를 인증하여 계정 해킹 방지</p>
<br/>
<p><strong>위치 권한</strong></p>
<p>사용자의 위치 정보를 수집하여, 근처의 게이머와 함께 게임을 즐기실 수 있습니다</p>
<br/>
</ul>

사용자가 권한 요청 페이지에 있는 확정 버튼을 클릭하면, 필요 권한 의 요청 절차가 시작됩니다.

이 과정에서, 필요 권한을 획득하기 위해 사용자에게 폴링 문의를 할 수 있습니다. App 에 필요한 권한을 values/msdk_permission_list.xml 에 아래와 같이 설정해야 합니다.

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <array name="msdk_permission_list">
        <item>android.permission.WRITE_EXTERNAL_STORAGE</item>
        <item>android.permission.READ_PHONE_STATE</item>
    </array>
</resources>

이 설정에서는 외부 기억 장치 와 단말기 상태 확인 , 두 개의 필요 권한을 설정합니다. 위 그림에서 이 두 가지 권한(권한이 부여되지 않은 경우)을 팝업하여 신청합니다.

3.3 테스트 검증

1. 사용자는 프로토콜 페이지에서 동의를 클릭한 후, TDM 를 실행하여 데이터베이스 관리와 디바이스 정보를 보고합니다. MSDK 어시를 통해 검증 협조를 구할 수 있습니다；
   
2. msdk_permission_list.xml 에 필요한 권한과 msdk_permission_content.html 의 하이라이트（필수）된 권한이 일치하여야 합니다；
   
3. 핵심 경로 테스트：구조적 메시지로 게임 소환, 애플리케이션 작동, 재정의 설치 등；