輕鬆構建遊戲登入能力，打造玩家流暢體驗

遊戲登入是玩家進入遊戲世界的重要步驟，是玩家進入遊戲後接觸到的第一個可以互動的介面，它看似簡單，但卻意義重大。遊戲登入不僅是進入遊戲的必要步驟，也是保障遊戲體驗、資料安全和社群互動的關鍵環節。

HarmonyOS SDK遊戲服務（Game Service Kit）主要提供快速、低成本構建遊戲基本能力與遊戲場景最佳化服務，有效提升遊戲開發效率，幫助您進行遊戲運營。遊戲服務提供遊戲登入能力，允許使用者使用華為賬號登入遊戲，從而迅速推廣遊戲，共享華為龐大的使用者價值。

遊戲登入包含使用華為賬號登入、使用遊戲官方賬號登入場景。接入遊戲登入後，遊戲啟動時會進行初始化，並向玩家展示聯合登入皮膚，玩家可以選擇任意一種方式進入遊戲。

場景介紹

使用華為賬號登入

轉移場景

將玩家的遊戲進度從HarmonyOS/EMUI系統渠道包轉移至HarmonyOS NEXT系統包體，即將該華為賬號與該遊戲HarmonyOS/EMUI系統下渠道包對應的玩家標識ID的值，轉移至該華為賬號在該遊戲HarmonyOS NEXT系統包體對應的玩家標識ID上。轉移成功後，玩家可以使用華為賬號進入HarmonyOS NEXT遊戲，但無法再透過該華為賬號進入HarmonyOS/EMUI遊戲。

關聯場景（快捷登入）

使用者授權提供手機號，實現透過華為賬號快速建立或關聯一個遊戲官方賬號並進入遊戲。

使用遊戲官方賬號登入

直接透過遊戲官方賬號登入遊戲，使用者體驗和遊戲官方包保持一致。

開發步驟

注：遊戲登入涉及的具體步驟請參考接入指南，本文僅闡述關鍵開發步驟。

聯合登入

初始化成功後，遊戲可呼叫unionLogin介面進行聯合登入，Game Service Kit向玩家展示聯合登入彈框。

let context = getContext(this) as common.UIAbilityContext;
let thirdAccountInfo1: gamePlayer.ThirdAccountInfo = {
  'accountName': 'testName1', // 遊戲開放給玩家接入的賬號型別名字，例如"官方賬號"、"xx賬號"等，並不是具體某個玩家ID或開發者ID。
  'accountIcon': $r('app.media.icon') // 遊戲官方賬號圖示資源資訊
};
let request: gamePlayer.UnionLoginParam = {
  showLoginDialog: true,
  thirdAccountInfos: [
    thirdAccountInfo1    
  ]
};
try {
  gamePlayer.unionLogin(context, request).then((result: gamePlayer.UnionLoginResult) => {
    hilog.info(0x0000, 'testTag', `Succeeded in logining: ${result?.accountName}`);
  }).catch((error: BusinessError) => {
    hilog.error(0x0000, 'testTag', `Failed to login. Code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  let err = error as BusinessError;
  hilog.error(0x0000, 'testTag', `Failed to login. Code: ${err.code}, message: ${err.message}`);
}

華為賬號認證與授權

遊戲判斷accountName為"hw_account"時，可根據needBinding值選擇透過Account Kit對應的建立授權/登入請求介面，獲取用於伺服器校驗的Authorization Code資訊。

需要華為玩家標識與遊戲官方賬號繫結（needBinding為true）

1.呼叫createAuthorizationWithHuaweiIDRequest建立授權請求並設定引數。

// 建立授權請求，並設定引數
let authRequest = new authentication.HuaweiIDProvider().createAuthorizationWithHuaweiIDRequest();
// 獲取頭像、暱稱以及手機號授權需要傳如下scope
authRequest.scopes = ['profile', 'phone'];
// 若開發者需要進行服務端開發，則需傳如下permission獲取authorizationCode
authRequest.permissions = ['serviceauthcode'];
// 使用者是否需要登入授權，該值為true且使用者未登入或未授權時，會拉起使用者登入或授權頁面
authRequest.forceAuthorization = true;
authRequest.state = util.generateRandomUUID();

2.呼叫AuthenticationController物件的executeRequest方法執行授權請求，並在Callback中處理授權結果，從授權結果中解析出頭像暱稱。

// 執行授權請求
try {
  let controller = new authentication.AuthenticationController(getContext(this));
  controller.executeRequest(authRequest, (err, data) => {
    if (err) {
      hilog.error(0x0000, 'testTag', `Failed to authenticate. Code: ${err.code}, message: ${err.message}`);
      return;
    }
    let authorizationWithHuaweiIDResponse = data as authentication.AuthorizationWithHuaweiIDResponse;
    let state = authorizationWithHuaweiIDResponse.state;
    if (state != undefined && authRequest.state != state) {
      hilog.error(0x0000, 'testTag', `Failed to authenticate. State is different.`);
      return;
    }
    hilog.info(0x0000, 'testTag', `Succeeded in authenticating.`);
    let authorizationWithHuaweiIDCredential = authorizationWithHuaweiIDResponse.data!;
    let avatarUri = authorizationWithHuaweiIDCredential.avatarUri;
    let nickName = authorizationWithHuaweiIDCredential.nickName;
    let authorizationCode = authorizationWithHuaweiIDCredential.authorizationCode;
    // 開發者處理vatarUri, nickName, authorizationCode資訊
  });
} catch (error) {
  let err = error as BusinessError;
  hilog.error(0x0000, 'testTag', `Failed to authenticate. Code: ${err.code}, message: ${err.message}`);
}

不需要華為玩家標識與遊戲官方賬號繫結（即needBinding為false）

1.呼叫createLoginWithHuaweiIDRequest建立登入請求並設定引數。

// 建立登入請求，並設定引數
let loginRequest = new authentication.HuaweiIDProvider().createLoginWithHuaweiIDRequest();
// 當使用者未登入華為賬號時，是否強制拉起華為賬號登入介面
loginRequest.forceLogin = true;
loginRequest.state = util.generateRandomUUID();

2.呼叫AuthenticationController物件的executeRequest方法執行登入請求，並在Callback中處理登入結果，獲取到Authorization Code。

// 執行登入請求
try {
  let controller = new authentication.AuthenticationController(getContext(this));
  controller.executeRequest(loginRequest, (err, data) => {
    if (err) {
      hilog.error(0x0000, 'testTag', `Failed to login. Code: ${err.code}, message: ${err.message}`);
      return;
    }
    let loginWithHuaweiIDResponse = data as authentication.LoginWithHuaweiIDResponse;
    let state = loginWithHuaweiIDResponse.state;
    if (state != undefined && loginRequest.state != state) {
      hilog.error(0x0000, 'testTag', `Failed to login. State is different.`);
      return;
    }
    hilog.info(0x0000, 'testTag', `Succeeded in logining.`);

    let loginWithHuaweiIDCredential = loginWithHuaweiIDResponse.data!;
    let authorizationCode = loginWithHuaweiIDCredential.authorizationCode;
    // 開發者處理authorizationCode
  });
} catch (error) {
  let err = error as BusinessError;
  hilog.error(0x0000, 'testTag', `Failed to login. Code: ${err.code}, message: ${err.message}`);
}

關聯遊戲官方賬號

當聯合登入介面獲取的needBinding值為true時，遊戲可呼叫bindPlayer介面繫結華為玩家標識teamPlayerId與遊戲官方賬號。

let context = getContext(this) as common.UIAbilityContext;
let thirdOpenId = '123xxxx'; // thirdOpenId表示遊戲官方賬號ID
let teamPlayerId = '456xxx'; // teamPlayerId表示玩家華為賬號對應的teamPlayerId
try {
  gamePlayer.bindPlayer(context, thirdOpenId, teamPlayerId).then(() => {
    hilog.info(0x0000, 'testTag', `Succeeded in binding.`);
  }).catch((error: BusinessError) => {
    hilog.error(0x0000, 'testTag', `Failed to bind. Code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  let err = error as BusinessError;
  hilog.error(0x0000, 'testTag', `Failed to bind. Code: ${err.code}, message: ${err.message}`);
}

未成年人防沉迷

呼叫verifyLocalPlayer介面進行賬號實名認證和遊戲防沉迷管控合規校驗。

let context = getContext(this) as common.UIAbilityContext;
let request: gamePlayer.ThirdUserInfo = {
  thirdOpenId: '123xxxx', // 遊戲官方賬號ID
  isRealName: true // 玩家是否實名,該值為true時表示已實名,為false時表示未實名
};
try {
  gamePlayer.verifyLocalPlayer(context, request).then(() => {
    hilog.info(0x0000, 'testTag', `Succeeded in verifying.`);
  }).catch((error: BusinessError) => {
    hilog.error(0x0000, 'testTag', `Failed to verify. Code: ${error.code}, message: ${error.message}`);
  });
} catch (error) {
  let err = error as BusinessError;
  hilog.error(0x0000, 'testTag', `Failed to verify. Code: ${err.code}, message: ${err.message}`);
}

提交玩家角色資訊

玩家成功登入遊戲並選擇角色、區服後，遊戲需要呼叫savePlayerRole介面，將玩家角色資訊上報至華為伺服器。

let context = getContext(this) as common.UIAbilityContext;
let request: gamePlayer.GSKPlayerRole = {
  roleId: '123',   // 玩家角色ID，如遊戲沒有角色系統，請傳入"0"，務必不要傳""和null。
  roleName: 'Jason', // 玩家角色名，如遊戲沒有角色系統，請傳入"default"，務必不要傳""和null。
  serverId: '456',
  serverName: 'Zhangshan',
  gamePlayerId: '789', // 若是轉移場景，請根據實際獲取到的gamePlayerId傳值。
  teamPlayerId: '345', // 若是關聯場景，請根據實際獲取到的teamPlayerId傳值。
  thirdOpenId: '123'   // 若遊戲官方賬號登入，請根據實際獲取到的thirdOpenId傳值。
};
try {
  gamePlayer.savePlayerRole(context, request).then(() => {
     hilog.info(0x0000, 'testTag', `Succeeded in saving.`);
  });
} catch (error) {
  let err = error as BusinessError;
  hilog.error(0x0000, 'testTag', `Failed to save. Code: ${err.code}, message: ${err.message}`);
}

瞭解更多詳情>>

訪問遊戲服務聯盟官網

獲取基礎遊戲服務功能開發指導文件