[업데이트 소식] NEW! 에러 핸들러 사용법 및 주의점
안녕하세요?
개발이 필요 없는 게임 서버, 뒤끝입니다.
지난 10월 SDK 5.9.0 업데이트로 뒤끝 에러 핸들러 기능이 추가되었습니다.
상황 별로 아래와 같이 총 5가지 에러 핸들러를 제공하고 있는데요.
▪️ 다른 기기에서 로그인 감지 시 호출되는 핸들러
▪️ 서버 점검 에러 발생 시 호출되는 핸들러
▪️ 과도한 요청(403 Forbidden) 감지 시 호출되는 핸들러
▪️ 과도한 요청 지속(403 Forbidden by Local) 시 호출되는 핸들러
▪️ 디바이스 차단 시 호출되는 핸들러
오늘은 위 핸들러들을 이용하는 방법과, 이용 시 주의해야 할 점을 안내드리겠습니다.
목차는 다음과 같습니다.
✅ 목차
🌱 핸들러란?
원래 뒤끝 베이스는 함수를 호출하고 그 함수에서 리턴 값을 받아 활용하는 방식인데요! 핸들러는 함수를 호출하지 않아도 자동으로 특정 상황에 따라 리턴되는 방식으로 작동합니다.
예시) 채팅에서 아무것도 하지 않고 타인의 메시지를 받는 형식
🌱 에러 핸들러란?
같은 맥락에서 에러 핸들러 역시, 호출한 함수의 리턴 값을 활용하는 것이 아니라
특정 에러가 발생하면 자동으로 호출되는 기능입니다.
[1] 이용 방법
STEP 1. 에러 핸들러 초기화 함수 추가하기
가장 먼저 해야 할 일은, 뒤끝 ErrorHandler를 초기화하는 것입니다.
아래 함수를 뒤끝 초기화 함수 호출 이후에 실행될 수 있도록 삽입해 주세요.
public BackendReturnObject InitializePoll(bool useAsnycPoll);
이때 초기화에 사용하는 useAsnycPoll은 핸들러가 그대로 외부 쓰레드에서 실행될지, 아니면 메인 쓰레드로 옮긴 이후에 동작 시킬지를 정하는 값인데요.
유니티의 UI 기능은 메인 쓰레드에서만 작동하기 때문에, 외부 쓰레드에서 함수를 호출할 경우 에러가 발생하게 됩니다. 그래서 만약 에러 핸들러 내부에서 UI에 접근하는 코드가 있을 경우 userAsnycPoll을 true 로, 없을 경우에는 false 로 설정해 주어야 합니다.
if (Backend.IsInitialized) {
Backend.ErrorHandler.InitializePoll(true);
}
다만 위와 같이 userAsnycPoll이 true일 경우에는 핸들러가 호출되는 것을 체크하기 위해서, Update 함수를 지속적으로 호출해 주어야 합니다. 관련하여 Update 문의 코드 추가에 약간의 리소스가 더 필요하다는 점 참고해 주세요.
STEP 2. 핸들러 설정하기
폴링 초기화를 세팅해 주셨다면, 이제 핸들러를 설정할 차례입니다.
각 상황마다 유저에게 노출할 안내 메시지를 작성해 줍니다.
여기서 핸들러는 앞서 말씀드린 것처럼, 특정 상황이 발생했을 때 호출될 뿐 인자 값은 전달해 주지 않는다는 점 명심해 주세요.
Backend.ErrorHandler.OnMaintenanceError = () => {
Debug.Log("점검 에러 발생!!!");
gameObject.GetComponentInChildren<Text>().text = "점검 중입니다.";
};
Backend.ErrorHandler.OnTooManyRequestError = () => {
Debug.Log("403 에러 발생!!!");
gameObject.GetComponentInChildren<Text>().text = "과도한 요청이 감지되었습니다.";
};
Backend.ErrorHandler.OnTooManyRequestByLocalError = () => {
Debug.Log("403 로컬 에러 발생!!!");
gameObject.GetComponentInChildren<Text>().text = "과도한 요청중입니다.";
};
Backend.ErrorHandler.OnOtherDeviceLoginDetectedError = () => {
Debug.Log("리프레시 불가!!!");
gameObject.GetComponentInChildren<Text>().text = "다른 기기에서 로그인이 감지되었습니다.";
};
STEP 3. Poll 호출하기
*ErrorHandler.InitializePoll에서 false로 호출할 경우 해당 함수는 호출하지 않아도 됩니다.
Poll은 핸들러가 호출될 때, 등록된 함수 내용을 외부 쓰레드에서 메인 쓰레드로 이동시켜 줍니다.
즉 Poll은 매초마다 ‘외부 쓰레드에 반응이 있나?’ 체크를 하고 반응이 잡히면 이것을 메인 쓰레드로 이동시켜주는 전달자 역할을 한다고 보시면 됩니다. 이를 통해 핸들러에서도 Unity.UI에 접근이 가능해집니다.
아래 전체 로직을 공유드리니, 확인해 주세요!
public class BackendErrorManager : MonoBehaviour {
void Start() {
if (Backend.IsInitialized) {
Backend.ErrorHandler.InitializePoll(true);
Backend.ErrorHandler.OnMaintenanceError = () => {
Debug.Log("점검 에러 발생!!!");
gameObject.GetComponentInChildren<Text>().text = "점검 중입니다.";
};
Backend.ErrorHandler.OnTooManyRequestError = () => {
Debug.Log("403 에러 발생!!!");
gameObject.GetComponentInChildren<Text>().text = "과도한 요청이 감지되었습니다.";
};
Backend.ErrorHandler.OnTooManyRequestByLocalError = () => {
Debug.Log("403 로컬 에러 발생!!!");
gameObject.GetComponentInChildren<Text>().text = "과도한 요청중입니다.";
};
Backend.ErrorHandler.OnOtherDeviceLoginDetectedError = () => {
Debug.Log("리프레시 불가!!!");
gameObject.GetComponentInChildren<Text>().text = "다른 기기에서 로그인이 감지되었습니다.";
};
}
}
void Update() {
Backend.ErrorHandler.Poll();
}
}
[2] 주의점
1. 다음 에러 핸들러는, 반드시 뒤끝 인스펙터에서 Auto Refresh Token을 활성화 해 주어야 합니다.
▪️ 다른 기기에서 로그인 감지 시 호출되는 핸들러
▪️ 디바이스 차단 시 호출되는 핸들러
다른 기기에서 로그인 감지 핸들러와, 디바이스 차단 핸들러는 모두 bad accesstoken 발생 후 토큰을 재발급하였을 때 나타날 수 있는 에러들입니다.
따라서 아래 체크박스를 반드시 활성화하여, 토큰 재발급이 자동(Auto Refresh Token)으로 실행되도록 설정해 주셔야 핸들러가 정상 작동하게 됩니다.
2. 다음 두 가지 에러 핸들러는, 비슷해 보이지만 다른 핸들러입니다.
▪️ 과도한 요청(403 Forbidden) 감지 시 호출되는 핸들러
▪️ 과도한 요청 지속(403 Forbidden by Local) 시 호출되는 핸들러
위 핸들러들은 공통적으로 5분간 유저가 500개 이상의 호출을 했을 때 발생하는 403 Forbidden에 대한 에러를 다루고 있습니다.
하지만 출력되는 메시지가 서로 다른데요!
과도한 요청 감지 시’는 말 그대로 해당 에러가 발생한 순간에 호출되는 핸들러로, 한 번만 호출이 됩니다. 이후 해당 유저가 보내는 모든 요청은 5분 동안 제한됩니다.
만약 여기서, 유저가 또 다시 요청을 한다면 어떤 일이 발생할까요?
바로 이때 ‘과도한 요청 지속 시’ 호출되는 핸들러가 사용됩니다. 즉, 유저의 요청이 제한되는 5분 동안은 함수가 호출될 때마다 해당 핸들러가 호출되는 것입니다.
3. 뒤끝 에러 핸들러는 언제 호출되나요? 콘솔에서 변경하자마자 바로는 안 되더라고요.
우선, 뒤끝은 웹서버 형식으로 작동한다는 것을 알아 두셔야 합니다. 서버에 소켓을 연결하고 실시간으로 데이터를 주고받는 형식이 아니기 때문에, 뒤끝 콘솔에서 점검을 설정하거나 디바이스를 차단해도 실시간으로 에러가 발생하지 않는 것이 정상입니다.
오늘 소개한 핸들러들은 서버에 요청을 하고 해당 요청에 대한 응답을 받을 때, 즉 요청한 뒤끝 함수가 리턴될 때 그 안에 있는 에러를 체크하는데요.
이 부분은 서버 점검 사례를 예시로 들어 설명드리겠습니다. 작동 방식은 다음과 같습니다.
① 개발자가 뒤끝 콘솔에서 점검 설정을 합니다.
② 유저가 게임을 하다가 뒤끝 함수를 호출합니다. (예를 들면 데이터 저장, 랭킹 불러오기 등)
③ 이때 2번 함수에서는 401 maintanance로 에러가 리턴이 됩니다.
④ 그 순간 에러핸들러는 2번에서 발생한 에러를 체크하고, 상황에 맞는 '서버 점검 에러 발생 시 호출되는 핸들러'를 작동시킵니다.
⑤ 작동된 서버 점검 에러 핸들러는 등록된 코드(개발자가 작성한 괄호 안 코드)를 실행시킵니다.
때문에 핸들러가 발생하는 경우는, 유저가 함수를 호출하고 응답을 받을 때밖에 없습니다. 만약 ②번에서 유저가 함수 호출을 하지 않고 기다리게 된다면? 핸들러가 호출되지 않게 되는 것입니다.
지금까지 ‘에러 핸들러’ 기능에 대해 알아보았습니다.
그렇다면 궁극적으로 이 기능의 이점은 무엇일까요?
실제로 서버 점검 기능이 출시되었을 때, 많은 분들이 뒤끝의 모든 함수에 서버 점검 함수를 호출하는 것에 부담을 느끼셨을 텐데요. 에러 핸들러를 활용해 보시면, 이전처럼 모든 함수마다 에러 대응을 각각 해주어야 하는 번거로움을 해결할 수 있습니다.
그럼 짧은 코드 하나로 에러 표시를 쉽게 할 수 있는 뒤끝 에러 핸들러를 사용해 보시기를 추천 드리면서, 이만 인사 드리겠습니다.
앞으로도 개발자 여러분의 게임 개발을 든든히 뒷받침하는 뒤끝이 되겠습니다.
감사합니다😊
