게임

게임 모듈은 게임 관련 다양한 기능을 제공합니다. 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. 초대 결과 콜백 처리
};

---