04/28/2025 20:45:30

로그인 모듈

1 개요

MSDK 로그인 기능은 게임에서 편리하게 로그인 할 수 있게 본 기능을 제공합니다：유저는 QQ, Wechat, Facebook, GameCenter, Google, 게스트 계정 등을 사용하여 귀하의 게임에 로그인 할 수 있습니다.

지원하는 채널：

1. WeChat
2. QQ
3. Guest
4. Facebook
5. GameCenter
6. Google
7. Twitter
8. Garena
9. Line
10. Apple
11. Kwai
12. HMS

2 연동 가이드

2.1 API 호출

추천 로그인 프로세스

1. SDK 초기화
2. 로그인 콜백 등록
3. 자동 로그인 호출
4. 자동 로그인 실패 시 로그인 지정 채널 선택
5. 로그인 프로세스 완료

콜백 등록

1）기능 설명
MSDK 로그인 모듈의 콜백을 받으려면 게임에 콜백 함수를 등록하여야 합니다; 애플리케이션 실행 함수에 게임 등록을 강력히 권장드립니다.

2）인터페이스 성명

/// <summary>
/// 로그아웃 콜백, 애플리케이션에서 콜백 소환
/// </summary>
public static event OnMSDKRetEventHandler<MSDKBaseRet> LoginBaseRetEvent;

/// <summary>
//// 로그인 콜백, login, bind, autologin, switchuser 등 포함
/// </summary>
public static event OnMSDKRetEventHandler<MSDKLoginRet> LoginRetEvent;

class MSDKLoginObserver
{

public:
    // 로그인 콜백, login, bind, autologin, switchuser 등 포함
    virtual void OnLoginRetNotify(const MSDKLoginRet &loginRet) {};

    // 로그아웃 콜백, 애플리케이션에서 콜백 소환
    virtual void OnBaseRetNotify(const MSDKBaseRet &baseRet) {};
};

3）예시 코드

MSDKLogin.LoginRetEvent += OnLoginRetEvent;
MSDKLogin.LoginBaseRetEvent += OnLoginBaseRetEvent;

private void OnLoginRetEvent(MSDKLoginRet loginRet)
{
	Debug.Log ("OnLoginRetNotify in Login");
	string methodTag = "";
	if (loginRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_LOGIN) {
		methodTag = "Login";
	} else if (loginRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_BIND) {
		methodTag = "Bind";
	} else if (loginRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_AUTOLOGIN) {
		methodTag = "AutoLogin";
	} else if (loginRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_QUERYUSERINFO) {
		methodTag = "QueryUserInfo";
	}
    // GetLoginRet 는 동기화 인터페이스이므로 콜백에서 처리할 필요가 없습니다
//      else if (loginRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_GETLOGINRESULT) {
	//	methodTag = "GetLoginResult";
	//}
    else if (loginRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_LOGINWITHCONFIRMCODE) {
		methodTag = "LoginWithConfirmCode";
	}
	SampleInstance.showRetDialog(methodTag, loginRet);
}			

private void OnLoginBaseRetEvent(MSDKBaseRet baseRet)
{
	Debug.Log ("OnBaseRetNotify in Login");

	if (baseRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_WAKEUP) {
		handleDiifAccount(baseRet);
	}
	else if (baseRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_LOGOUT) {
		string methodTag = "Logout";
	    SampleInstance.showRetDialog(methodTag, baseRet);
	}
}

// 이상 계정 처리 로직
private void handleDiifAccount (MSDKBaseRet baseRet)
{
    string methodTag = "이상 계정";
    switch (baseRet.RetCode) {
    case MSDKError.SUCCESS: { // 로컬 기존 ticket이 유효하며, 기존 토큰을 사용하여 로그인 할 수 있습니다
            SampleInstance.showRetDialog (methodTag, "기존 ticket을 사용하여 로그인 할 수 있으므로 별다른 처리가 필요없습니다");
            break;
        }
    case MSDKError.LOGIN_ACCOUNT_REFRESH: { // 신-구버전 openid 가 동일하지만, ticket이 다릅니다. 로그인 ticket을 새로고침하세요
            SampleInstance.showRetDialog (methodTag, "신-구버전 openid 가 동일하지만 ticket이 다릅니다. 로그인 ticket을 새로고침하십시오");
            break;
        }
    case MSDKError.LOGIN_URL_USER_LOGIN: {// 로컬에 openid 없음. ticket 을 끌어올려 새로운 ticket으로 로그인하세요
            SampleInstance.showRetDialog (methodTag, "로컬에openid 가 없습니다. ticket 을 끌여올려 새로운 ticket으로 로그인하십시오. 게임 계정 로직（SwitchUser） 을 자동 트리거하여 게임 로그인의 콜백 결과를 모니터링 합니다");
            break;
        }
    case MSDKError.LOGIN_NEED_SELECT_ACCOUNT: {
            SampleInstance.ShowSwithUserDialog ();
            break;
        }
    case MSDKError.LOGIN_NEED_LOGIN: {
            SampleInstance.showRetDialog (methodTag, "ticket이 유효하지 않으므로 로그인 페이지로 들어갑니다");
        }
        break;
    default:
        break;
    }
}

//폐기 시 리스너를 제거합니다
private void OnDestroy()
{
	MSDKLogin.LoginRetEvent -= OnLoginRetEvent;
	MSDKLogin.LoginBaseRetEvent -= OnLoginBaseRetEvent;
}

MSDKLogin::SetLoginObserver(new MSDKDemoBaseLoginObserver());

class  MSDKDemoBaseLoginObserver: public GCloud::MSDK::MSDKLoginObserver {
    // 로그인 콜백, login, bind, autologin, switchuser 등 포함
public:
    virtual void OnLoginRetNotify(const GCloud::MSDK::MSDKLoginRet &loginRet) {
        String ret = MSDKUtils::FormatJson(MSDKJsonManager::ToJson(loginRet));
        UMSDKDemoBase::showNormalAlert(ret);
    };
    // 로그아웃 콜백, 애플리케이션에서 콜백 소환
    virtual void OnBaseRetNotify(const GCloud::MSDK::MSDKBaseRet &baseRet) {
        String ret = MSDKUtils::FormatJson(MSDKJsonManager::ToJson(baseRet));
        if (baseRet.methodNameID == kMethodNameWakeUp) {
            //이상 계정 처리
            switch (baseRet.retCode) {
                case MSDKError::SUCCESS:
                	ret.append(""기존 ticket을 사용하여 로그인 할 수 있으므로 별다른 처리가 필요없습니다");
                    break;
                case MSDKError::LOGIN_ACCOUNT_REFRESH:
                	ret.append("신-구버전 openid 가 동일하지만 ticket이 다릅니다. 로그인 ticket을 새로고침하십시오");
                    break;
                case MSDKError::LOGIN_URL_USER_LOGIN:
                	ret.append("로컬에openid 가 없습니다. ticket 을 끌여올려 새로운 ticket으로 로그인하십시오. 게임 계정 로직（SwitchUser） 을 자동 트리거하여 게임 로그인의 콜백 결과를 모니터링 합니다");
                    break;
                case MSDKError::LOGIN_NEED_SELECT_ACCOUNT:
                	ret.append("사용자 전환 여부 선택");
                    break;
                case MSDKError::LOGIN_NEED_LOGIN:
                	ret.append("ticket이 유효하지 않으므로 로그인 페이지로 들어갑니다");
                    break;
                default:
                    break;
            }
            return;
        }
        if (baseRet.retCode == MSDKError::NEED_REALNAME) {
            //실명제는 처리할 필요가 없습니다
            return;
        }
        UMSDKDemoBase::showNormalAlert(ret);
    };
};

4）데이터 구조

MSDKLoginRet 상세 해석
MSDKBaseRet 에서 이어받아, 아래의 기초적인 정보 포함하고 있습니다

자동 로그인

1）기능 설명
자동 로그인, MSDK 는 로컬 로그인 상태를 자동으로 획득하여 MSDK 서버에서 로그인 상태가 유효한지 점검합니다. 로컬에 로그인 상태 캐시가 없거나 또는 서버에 로그인 상태 실효 리턴이 되면, 자동 로그인 실패 결과가 콜백됩니다.

2）인터페이스 성명

public static void AutoLogin();

public static void AutoLogin();

3）예시 코드

MSDKLogin.AutoLogin();

MSDKLogin::AutoLogin();

로그인

1）기능 설명
지정된 채널에 로그인하여, 제3자 플랫폼의 로그인 상태를 획득한 후 MSDK 서버 인증 으로 이동하여 MSDK 통합 계정을 리턴 받습니다.
현재 Wechat 채널만 QR코드 로그인이 지원되고 있으며, 자세한 사항은 Wechat 채널의 로그인 기능 을 참조하십시오.

2）인터페이스 성명

public static void Login(string channel, string permissions = "", string subChannel = "", string extraJson = "")

public static void Login(const String &channel, const String &permissions, const String &subChannel, const String &extraJson)

3）파라미터 설명

4）예시 코드

MSDKLogin.Login(MSDKChannel.WeChat);

std:string permissionList = "snsapi_userinfo,snsapi_friend,snsapi_message";
MSDKLogin::Login("WeChat", permissionList);

로그아웃

1）기능 설명
로그아웃 채널

2）인터페이스 성명

public static void Logout(string channel = "", string subChannel = "", bool channelOnly = false)

public static void Logout(const String &channel = "", const String &subChannel = "", const bool channelOnly = false)

3）예시 코드

MSDKLogin.Logout();

MSDKLogin::Logout();

로그인 상태 획득

1）기능 설명
게임에서 로그인 상태 정보 획득

[warning] 본 인터페이스에서 로그인 상태 유효기간이 지난 검증은 제거되었습니다.

2）인터페이스 성명

public static MSDKLoginRet GetLoginRet()

public static bool GetLoginRet(MSDKLoginRet &loginRet)

3）예시 코드

MSDKLoginRet ret = MSDKLogin.GetLoginRet();

MSDKLoginRet ret;
MSDKLogin::GetLoginRet(ret);

게임 계정 전환

1）기능 설명
다른 계정이 발생하는 경우, 다른 계정으로 로그인 할 지 선택하여야 합니다. 다른 계정 상황: 예를 들어 QQ 로 로그인한 경우, Home 버튼을 눌러 바탕화면으로 돌아온 뒤, Wechat 게임 센터에서 게임을 실행하면 Wechat 계정으로 전환하는지를 묻는 창이 뜹니다. 일반적으로 국내에서는 다른 계정 상황이 발생할 수 있습니다.

2）인터페이스 성명

public static bool SwitchUser(bool useLaunchUser)

public static bool SwitchUser(bool useLaunchUser);

3）파라미터 설명

[info] 주의사항
1.유저가 계정 전환을 선택한 경우, useLaunchUser 를 true 로 설정하십시오. 전환 계정의 결과는 게임 모니터링 로그인 콜백에서 리턴됩니다.
2.유저가 계정 전환을 선택하지 않은 경우, useLaunchUser 를 false 로 설정하십시오. MSDK 는 자동으로 자동 로그인 로직을 트리거하며, 게임으로 콜백하지 않습니다

4）예시 코드

MSDKLogin.SwitchUser(true);

MSDKLogin::SwitchUser(true);

바인드(해외만 지원)

1）기능 설명
연동의 본질은 여러 개의 제3자 계정을 하나의 MSDK openid 로 통합하는 것입니다. 일반적으로 사용되는 상황은：게스트 로그인 방식으로 게임에 로그인 한 뒤, Facebook 또는 Google 계정으로 연동하는 것입니다.

2）인터페이스 성명

public static void Bind(string channel, string permissions = "", string subChannel = "", string extraJson = "")

public static void Bind(const String &channel, const String &permissions = "", const String &subChannel = "", const String &extraJson = "")

3）파라미터 설명

4）예시 코드

MSDKLogin.Bind("WeChat");

MSDKLogin::Bind("WeChat");

확인코드를 사용하여 로그인

1）기능 설명
로그인이나 연동에 실패한 경우, 확인코드를 통해 다시 로그인을 시도합니다. 이 기능을 사용하게 되면, 사용자가 다시 로그인 인터페이스를 소환하여 승인을 요청하지 않아도 됩니다. 확인코드는 서버에서 리턴합니다.

2）인터페이스 성명

public static void LoginWithConfirmCode (int actionType = 0, string confirmcode = "",string extraJson = "")

public static void LoginWithConfirmCode(const int actionType = 0, const String &confirmCode = "", const String &extraJson = "");

3）파라미터 설명

4）예시 코드

MSDKLogin.LoginWithConfirmCode(0, confirmcode);

MSDKLogin::LoginWithConfirmCode(0, confirmcode);

게스트 기능 리셋

1）기능 설명
게스트 리셋 함.게스트 채널을 다시 사용하여 로그인 하는 경우, 새로운 게스트 아이디가 생성됩니다.

2）인터페이스 성명

public static void ResetGuest()

static void ResetGuest()

3）예시 코드

MSDKLogin.ResetGuest();

MSDKLogin::ResetGuest();

3 Editor 환경에서 시뮬레이션 로그인

개발 단계에서, Editor 환경에 로그인하여 통합 테스트를 진행하여야 합니다. MSDK 는 현재 업무측이 Editor 환경에서 통합 테스트를 할 수 있게 시뮬레이션 로그인 방법을 제공하고 있습니다.

자세한 사항은 Editor 환경에서 시뮬레이션 로그인 참조하십시오

4 게스트 모드와 바인드 기능 설명

4.1 기능 설명

게스트 모드: 사용자가 게스트의 신분으로 로그인（예：로그인 버튼 없이 게임 진입）하여, 게임 내 소셜 네트워킹 계정과 연계해 계정을 찾는/만드는 로그인 방식입니다.

사용되는 시나리오 설명：

1. 일반적으로 채널 로그인 버튼 없이 게스트 신분으로 게임 접속하기
2. 신규 유저 튜토리얼, 게임 설정 인터페이스에서 소셜 네트워킹 계정 연동 기능을 찾아볼 수 있으며, 계정 연동으로 사용자의 친구 리스트 획득과 계정 찾기 등을 할 수 있음

3. 계정 찾기는 계정 연동을 통해 트리거되며, 연동 계정에 진도가 있는 경우, 에러코드 및 확인코드가 리턴될 수 있으며, 확인코드를 통해 로그인 인터페이스를 호출하여 계정 복구를 할 수 있음

   

4.2 로그인

매번 게스트 채널을 통해 로그인을 할 수 있습니다

4.3 계정 연동

연동 인터페이스를 통한 계정 연동. 계정 연동을 통해 사용자의 관계 체인 획득 및 계정 찾기 등을 할 수 있게 됩니다.

[info] 테스트를 위해 계정 연동 해제를 해야 하는 경우, 기업 Wechat 으로 MSDK 도우미 에 연락하십시오

4.4 계정 복구

1. 연동 실패를 통해 트리거 되며, 연동 채널에 계정 진도가 진행 중일 때, 제3자 에러코드는：1403 입니다
2. 에러코드 판단을 통해 확인코드 로그인 인터페이스를 사용하여 로그인을 진행합니다

4.5 진도 리셋

게스트 로그인을 할 때마다, 사용자가 진도를 새로 설정하기를 원하는 경우, 게스트 인터페이스를 재설정하여 현재의 게스트（게스트만 삭제되며, 연동된 계정을 통해 기존 계정을 찾을 수 있습니다）를 삭제할 수 있습니다

주의사항：게스트 계정을 연동하지 않은 경우, 재설정 시 게사트 계정이 사라질 수도 있습니다

5 실명 인증

국가의 법률, 법규에 다르면 온라인 게임 사용자는 유효한 신분증을 사용하여 실명 인증을 해야 게임에 로그인을 할 수 있습니다. 게임 개발 단계에서의 부담을 줄이기 위해 게임 로그인 과정에서의 실명인증 단계를 캡슐화했습니다. 로그인 후, 만약 실명인증이 필요하다면, 자동으로 WebView 컴포넌트를 소환하여 실명 인증 페이지를 열게 됩니다. 사용자가 실명인증을 마치면, 게임에 로그인을 할 수 있게 되므로, 실명 인증 과정은 별도의 개발을 하지 않으셔도 됩니다.

[info] 주의사항：
1、실명 인증 시 WebView 컴포넌트에 접속해야 합니다
2、실명인증된 웹페이지는 전체 화면으로 디스플레이로, 사용자가 로그인으로 돌아가기 를 클릭하면 게임에 리턴되는 로그인 상태는 로그인 실패 입니다.
3、실명인증은 중독 방지 시스템에서 제공하는 관련 서비스입니다
4、실명인증 과정은 국내 게임에만 존재하며, 해외 게임에는 본 과정이 존재하지 않습니다

6 Universal Link 연동 기능 점검

버전 설명

V 5.11 또는 그 이상 버전

1）기능 설명

자가진단기능 을 추가하여 개발자가 SDK 접속 과정에서 발생하는 문제를 검색할 수 있도록 하였으며. 현재는 Wechat 채널, 테스트 환경에서 테스트용으로만 지원되며, 정식 환경에서는 이 기능을 사용할 수 없습니다

2) 인터페이스 코드

channel 은 “WeChat“ 을 입력하고, 기타 필드는 예약된 필드로 빈 문자열을 입력하면 됩니다

public static void CheckUniversalLink(string channel, string subChannel = "", string extraJson = "");

MSDK_EXPORT_UE static void CheckUniversalLink(const String &channel, const String &subChannel = "", const String &extra = "");

3) 예시 코드：

인터페이스 호출

MSDKLogin.CheckUniversalLink(("WeChat");

MSDKLogin::CheckUniversalLink("WeChat");

콜백 함수

// 로그아웃 콜백, 애플리케이션으로 콜백 소환
 public void OnLoginBaseRetEvent(MSDKBaseRet baseRet)
{
    Debug.Log("OnBaseRetNotify in Login");
    if (baseRet.MethodNameId == (int)MSDKMethodNameID.MSDK_LOGIN_CHECK_UL)
    {
        // 콜백 처리하여 Universal Link 결과 점검
    }
    mCurrentTestMgr.ShowLogInNewLine(methodTag + Tools.Instance.GetRetString(baseRet));
}

// 로그아웃 콜백, 애플리케이션으로 콜백 소환
void OnBaseRetNotify(const MSDKBaseRet &baseRet) {
    if (baseRet.methodNameID == kMethodNameCheckUniversalLink) {
        // 콜백 처리하여 Universal Link 결과 점검
    }
    handleCallback(baseRet, baseRet.methodNameID);
};

4) 필드 설명

그 중 점검 결과는 baseRet.ExtraJson 에, JSON 포맷 문자열로 보여집니다

{
    "success":true,
    "errorInfo":"Universal Link check passed. The application is launched by WeChat via Universal Link",
    "step":"WXULCheckStepBackToCurrentApp",
    "suggestion":""
}

success 표식은 현재 단계에서의 검측 결과
errorInfo 는 prompt information
suggestion 는 개발자에게 조작 정보를 prompt 할 때 사용
step 값 설명:
    step = WXULCheckStepParams: 파라미터 점검
    step = WXULCheckStepSystemVersion: 현재 시스템 버전 점검
    step = WXULCheckStepWechatVersion: Wechat 클라이언트 버전 점검
    step = WXULCheckStepSDKInnerOperation: Wechat SDK 내부 조작 점검
    step = WXULCheckStepLaunchWechat: App 에서 Wechat 소환 점검
    step = WXULCheckStepBackToCurrentApp: Wechat 에서 현재 App 으로 돌아가기 점검
    step = WXULCheckStepFinal: 최종 점검

이 7 개 step 을 순서대로 콜백 할 것이며, WXULCheckStepFinal 을 콜백했다는 것은 점검 통과를 의미하며 SDK  접속이 성공적임을 뜻합니다. 모든 step 에서 콜백된 success 는 false 이며, 프로세스가 종료되고, 추가적인 콜백이 발생하지 않습니다. errorInfo 에 따라 현재 step 에서의 잘못된 원인을 살펴볼 수 있으며 suggestion 에 따라 문제를 복구할 수 있습니다.

7 FAQ

1. 보안성을 보장하기 위해 MSDK 로그인 상태는 유효기한의 제한이 있으며, 일반적으로 30 일 입니다. 로그인 디바이스의 변경, 보안 문제 검토로 인해 MSDK 의 유효기한이 앞당겨질 수 있으며, 게임에서는 유효기한이 만료된 상황을 처리해야 합니다.
2. MSDK 5.4.0000 버전（GCloud 2.0.10 버전에 대응）부터 로그인 재입력 제한이 제거되지만, 로그인 시간 초과 제한은 계속 유지됩니다. iOS9 이상 시스템에서 시스템 왼쪽 상단 모서리의 “xx게임으로 돌아가기” 또는 home 버튼을 통해 바로 게임으로 돌아가는 경우, 로그인 콜백이 없으며, 로그인 인터페이스를 호출하여 로그인 프로세스（구버전은 InProgress 에러 리턴）를 다시 시작하여 다시 로그인을 합니다.
3. 모바일Q/ Wechat 게임센터에서 게임을 실행 했다는 것을 어떻게 판단하나요？
   MSDK5.2.000 버전 및 이전 버전의 경우, wakeup 콜백 ExtraJson 파라미터의 game_data 필드에서 판단할 수 있습니다. Wechat：WX_GameCenter, 모바일Q 는 sq_gamecenter 입니다.
   MSDK5.3.000 버전 및 이후 버전의 경우, wakeup 콜백 ExtraJson 파라미터의 param 필드에서 판단할 수 있습니다. 본 필드에서 게임센터에서 리턴하는 필드를 모두 수신합니다. 또한, game_data 에서도 이 필드를 수신하는데, 모바일 Q：launchfrom=sq_gamecenter; Wechat Android：_wxobject_message_ext:WX_GameCenter; Wechat iOS：messageExt:WX_GameCenter 입니다.
   
4. pay_token 을 어떻게 획득하나요？
   모바일Q 채널의 pay_token 은, 로그인 콜백 channelInfo 의 pay_token 필드를 해석하여 획득합니다；
   기타 채널에는 pay_token 이 없으며, MSDK 로그인 콜백 제일 바깥 레이어에는 token 필드가 있습니다. 이 중, 국내 게임은 token 처리가 필요 없으며, 해외 게임의 경우 제3자 채널 token 인터페이스을 사용하여 token 을 이에 대응하는 채널로 token 을 전환해야 합니다.
   주의：권장 결제 인증 방법은, 제3자 openid 와 token 을 획득한 후 지정 플랫폼에 결제 인증을 진행하는 것입니다.