遊戲

遊戲模組提供遊戲相關的各種功能，閱讀JOGOS_SDK 簡介頁面與您的遊戲引擎相關的部分後，可以按如下方式使用相關的功能：：

window.JOGOS_SDK.game;

若你需要於初始化階段完成本地化語言適配、設備適配、時間校準等配置操作，可跳轉至初始化（SysInfo）相關頁面，查看詳細的參數定義與配置方法。

遊戲暫停/繼續

遊戲中斷時（結束關卡、暫停遊戲等），必須呼叫遊戲暫停方法告知我們遊戲已經暫停，不要忘記在遊戲恢復或繼續時（恢復、復活、進入下一關等），呼叫繼續遊戲方法告訴我們遊戲已經繼續。SDK 內部會自動處理播放廣告時的暫停與繼續，無需重複呼叫。

// 告知我們遊戲已暫停
await window.JOGOS_SDK.game.pause();
// 告知我們暫停的遊戲已繼續
await window.JOGOS_SDK.game.continuePlay();

遊戲開始/結束載入

當您的遊戲開始載入時，必須呼叫開始載入方法告知我們遊戲開始載入，載入結束後，務必呼叫載入結束方法告知我們遊戲已經載入結束。

// 告知我們遊戲開始載入
await window.JOGOS_SDK.game.loadingStart();
// 告知我們遊戲載入已經結束
await window.JOGOS_SDK.game.loadingEnd();

當遊戲開始載入時，必須呼叫開始載入方法告知我們遊戲開始載入，載入結束後，必須呼叫載入結束方法告知我們遊戲已經載入結束。

// 告知我們遊戲已經暫停
await window.JOGOS_SDK.game.pause();
// 告知我們遊戲已經繼續
await window.JOGOS_SDK.game.continuePlay();

歡樂時光

可以在玩家達到某種成就（擊敗 Boss、達到高分等）時呼叫此方法，成功呼叫此方法後進觸發網站的慶祝動作（例如發射一些五彩紙屑）。完成關卡或獲得獎勵時，無需呼叫此方法。

// 激活遊戲歡樂時光
await window.JOGOS_SDK.game.happytime();

好友與聊天功能

我們已整合標準化社交功能模組，涵蓋好友關係管理與即時聊天服務。若您的遊戲支援多人互動玩法，可透過輕量級API快速接入，實現：好友列表雲端同步、一鍵邀請組隊、私密對話等核心社交場景。助力開發者以極低開發成本，高效構建遊戲內沉浸式社交生態體系。

• 開發者在使用時，需要傳遞對應玩家在平台側的 UserId 作為參數。

好友關係檢查

檢查指定玩家是否為當前使用者的好友。

/**
 * 檢查指定玩家是否我的好友
 * @param {Array<number>} userIds 玩家ID集合
 * @returns {Promise<Object>} { [userId: number]: boolean } 鍵值對物件
 */
window.JOGOS_SDK.game.isMyFriends = async function(userIds) {
    // 內部實現
}

好友交互邏輯說明

開發者需要根據好友關係自行實現按鈕顯示邏輯：

1. 按鈕狀態判斷：使用 isMyFriends 介面檢查指定玩家是否為好友
2. 按鈕顯示邏輯：
   • 如果是好友：顯示"Conversation"按鈕，點擊後呼叫 openChatDialog 發起聊天
   • 如果不是好友：顯示"Add Friend"按鈕，點擊後呼叫 sendFriendRequest 傳送好友申請
3. 按鈕實現：按鈕的UI樣式、位置、互動效果均由遊戲開發者自行實現

範例程式碼

// 實現好友互動按鈕的範例
async function setupFriendButton(userId, buttonElement) {
    try {
        // 1. 檢查好友關係
        const friendStatus = await window.JOGOS_SDK.game.isMyFriends([userId]);
        const isFriend = friendStatus[userId];
        
        // 2. 根據好友關係設定按鈕
        if (isFriend) {
            // 顯示聊天按鈕
            buttonElement.textContent = "Conversation";
            buttonElement.onclick = async () => {
                const success = await window.JOGOS_SDK.game.openChatDialog(userId);
                if (!success) {
                    alert("無法開啟聊天視窗，請確保在官方平台環境");
                }
            };
        } else {
            // 顯示新增好友按鈕
            buttonElement.textContent = "Add Friend";
            buttonElement.onclick = async () => {
                const success = await window.JOGOS_SDK.game.sendFriendRequest(userId);
                if (success) {
                    alert("好友申請已發送");
                } else {
                    alert("發送好友申請失敗");
                }
            };
        }
        
        // 3. 新增防頻繁點擊邏輯
        let lastClickTime = 0;
        const originalClick = buttonElement.onclick;
        buttonElement.onclick = function() {
            const now = Date.now();
            if (now - lastClickTime < 3000) {
                console.log("點擊過於頻繁，請稍後再試");
                return;
            }
            lastClickTime = now;
            originalClick.call(this);
        };
        
    } catch (error) {
        console.error("設定好友按鈕失敗:", error);
    }
}

新增好友

向指定玩家傳送好友申請。

/**
 * 向指定玩家傳送好友申請
 * @param {number} userId 目標玩家ID
 * @returns {Promise<boolean>} 是否發送成功
 */
window.JOGOS_SDK.game.sendFriendRequest = async function(userId) {
    // 內部實現
}

發起聊天

開啟與指定好友的聊天視窗。

/**
 * 開啟與指定玩家的聊天視窗
 * @param {number} userId 目標玩家ID
 * @returns {Promise<boolean>} 是否成功開啟
 */
window.JOGOS_SDK.game.openChatDialog = async function(userId) {
    // 內部實現
}

邊界處理：

• 非官方平台嵌入時回傳失敗並顯示提示："好友聊天功能僅在官方平台提供"
• 按鈕點擊後3秒內不可重複點擊

重要提醒

開發者的遊戲自有聊天功能：如果該遊戲（連網遊戲）自己擁有聊天功能，我們要求開發者新增髒話過濾器並根據遊戲設定禁用聊天。如有投訴，我們將要求您禁用聊天。

初始化介面會回傳邀請欄位參數

• 遊戲初始化介面增加邀請加入遊戲的自訂參數，如房間ID、邀請碼等，開發者可在分享邀請連結時攜帶這些參數，被邀請玩家透過連結進入遊戲時，SDK 會將參數傳遞給開發者，以便將玩家拉入對應房間。

// 遊戲初始化時傳遞房間參數（範例）
const gameConfig = {
    inviteArgs: 'ABC123',       // 自訂欄位（如邀請碼/房間ID）
    // 其他遊戲配置...
};

// 初始化SDK時傳遞參數
window.JOGOS_SDK.init({
    gameId: 'your_game_id',
    customParams: JSON.stringify(gameConfig)
});

開啟邀請好友視窗

• 當使用者處於遊戲中可加入新遊戲的位置時，此功能支援您在遊戲場景中放置"邀請分享"按鈕：
• 點擊按鈕可開啟一個包含邀請連結的彈窗，支援選擇好友傳送邀請。
• 邀請連結會攜帶自訂參數（如房間ID/邀請碼等），被邀請玩家點擊連結進入遊戲時，開發者可解析參數並將玩家拉入對應房間。
• 點擊遊戲場景中的"Invite friend"按鈕，開啟側邊好友列表欄，傳送邀請訊息給好友，支援透過連結或直接邀請方式加入遊戲。

/**
 * 開啟邀請視窗
 * @param {Object} inviteArgs 邀請參數物件
 * @param {string} inviteArgs.inviteArgs 自訂邀請參數（必填，如房間ID或邀請碼）
 * @param {string} [inviteArgs.customData] 自訂資料（將透傳給被邀請者）
 * @param {number} [inviteArgs.expireTime] 邀請連結過期時間戳記（毫秒）
 */
window.JOGOS_SDK.game.openInviteDialog = function(inviteArgs) {
    // 參數校驗
    if (!inviteArgs || !inviteArgs.inviteArgs) {
        throw new Error('Missing required parameter: inviteArgs');
    }
    
    // 內部實現：
    // 1. 生成帶參邀請連結
    // 2. 開啟邀請彈窗（含好友列表和分享選項）
    // 3. 處理邀請結果回呼
};

---