Game Ranking

Dùng cho game tổ chức các event để các user leo top trong bảng xếp hạng

Game Ranking đang hỗ trợ 4 loại ranking:

• Event Timeline: Là loại event mà tất cả các user cùng bắt đầu ở 1 thời điểm (startDate), và cùng kết thúc ở 1 thời điểm (endDate).

• Event Progress: Là loại event mà mỗi user sẽ bắt đầu ở 1 thời điểm, và kết thúc ở 1 thời điểm khác nhau.

• Leaderboard: Là 1 bảng xếp hạng điểm cho toàn bộ user của 1 app, một leaderboard sẽ có top 200 user được hiển thị, và được xếp hạng trong 10000 user, nếu nằm ngoài 10000 user thì thứ hạng sẽ là 10000+;

• Leaderboard Season: Là 1 bảng xếp hạng điểm cho toàn bộ user của 1 app trong 1 khoảng thời gian nhất định, một leaderboard sẽ có top 200 user được hiển thị, và được xếp hạng trong 10000 user, nếu nằm ngoài 10000 user thì thứ hạng sẽ là 10000+;

1. Loại Event Timeline

• Là event được diễn ra từ ngày startDate đến ngày endDate.

• Khi hết ngày endDate thì user sẽ không cập nhật được điểm nữa, và sẽ có thêm Y ngày để claim phần thưởng.

• Thời gian được tính theo giờ chuẩn UTC.

• Mỗi user tham gia sẽ được phân loại vào 1 bảng xếp hạng với số lượng user được cấu hình trên CMS của GSM.

• Mỗi event có 2 loại tính điểm là: Cộng dồn điểm và Điểm cao nhất

1.1 Lấy các events đang hoạt động

• Dùng để xem có các event nào đang hoạt động và xử lý theo từng loại event

• Client phải tự lưu điểm hiện tại của user tùy theo từng loại eventType

• Nếu eventType == 1 thì là loại event cộng dồn điểm

• Nếu eventType == 2 thì là loại event cập nhật điểm cao nhất

void GetActiveEventsData(double ratingPoint, Action<EventData[]> onComplete, Action<long, string> errorCallback = null)

Các tham số

• ratingPoint: Đây là điểm để phân cấp độ user

• onComplete: Hàm xử lý với param là mảng các event đang hoạt động.

• errorCallback: Hàm xử lý khi có lỗi xảy ra.

Code mẫu:

double ratingPoint = 20; //Đây là điểm để phân cấp độ user
GSM.Events.GSMEventTimeline.GetActiveEventsData(ratingPoint, events =>
{
    //Tiếp tục code logic với danh sách events
    foreach (GSM.Events.GSMEventTimeline.EventData eventData in datas)
    {
        //Nếu eventData.eventType == 1 thì là loại event cộng dồn điểm
        //Nếu eventData.eventType == 2 thì là loại event cập nhật điểm cao nhất
    }
});

1.2 Lấy các events đã hoàn thành

• Dùng để lấy các event đã hoàn thành sau đó sử dụng GSM.Events.GSMEventTimeline.ClaimReward("{finishEventId}"); để claim phần thưởng.

• Dữ liệu phần thưởng được trả về trường reward trong mỗi đối tượng EventFinishedData

void GetFinishEvents(Action<EventFinishedData[]> onComplete, Action<long, string> errorCallback = null)

Các tham số

• onComplete: Hàm xử lý với param là mảng các event đã hoàn thành.

• errorCallback: Hàm xử lý khi có lỗi xảy ra.

Code mẫu:

GSM.Events.GSMEventTimeline.GetFinishEvents(data =>
{
    foreach (GSM.Events.GSMEventTimeline.EventFinishedData eventFinish in data)
    {
        // Claim an event
        GSM.Events.GSMEventTimeline.ClaimReward(eventFinish.id, () =>
        {
            Debug.Log("Claim reward succeeded");
             string reward = eventFinish.reward;
            //Tiếp tục xử lý trả thưởng cho user
        }, () =>
        {
            Debug.Log("Claim reward failed");
        });
    }
});

1.3 Cập nhật điểm

• Dùng để cập nhật điểm hiện tại của user. Gửi lên khi user có sự thay đổi điểm. Điểm này cần được lưu trong dữ liệu local để tính toán chính xác.

• Ví dụ với loại event Cộng dồn điểm lần 1 user kiếm được 5 điểm, sau đó kiếm được tiếp 10 điểm thì lúc này số điểm sử dụng để cập nhật lên GSM là 15 điểm. Tức là tự phía game sẽ tính toán logic tính điểm theo từng loại event.

void UpdateScore(string eventId, int score)

Các tham số

• eventId: Id của sự kiện.

• score: Số điểm hiện tại của người chơi.

Code mẫu:

int score = 700; //Số điểm hiện tại mà client đang lưu trữ
string eventId = "648abb606bb077eb734a3099"; //Id của event đang hoạt động
GSM.Events.GSMEventTimeline.UpdateScore(eventId, score);

1.4 Lấy bảng xếp hạng

• Dùng để cập nhật điểm hiện tại của user và lấy bảng xếp hạng của user.

void UpdateScoreAndGetLeaderBoard(string eventId, int score, Action<UserData[]> onComplete, Action<long, string> errorCallback = null)

Các tham số

• eventId: Id của sự kiện.

• score: Số điểm hiện tại của người chơi.

• onComplete: Là hàm xử lý với danh sách các điểm của người chơi trong bảng xếp hạng (Trong UserData có trường isSelf=true thì đó là thông tin điểm của chính người chơi đó).

• errorCallback: Hàm xử lý khi có lỗi xảy ra.

Code mẫu:

int score = 700; //Số điểm hiện tại mà client đang lưu trữ
string eventId = "648abb606bb077eb734a3099"; //Id của event đang hoạt động
GSM.Events.GSMEventTimeline.UpdateScoreAndGetLeaderBoard(eventId, score, response =>
{
    Debug.Log(GSM.Extension.JsonHelper.ArrayToJsonString(response));
    //Do something
});

2. Loại Event Progress

• Là loại event mà mỗi user sẽ bắt đầu ở 1 thời điểm, và kết thúc ở 1 thời điểm khác nhau.

• Mỗi một event thì có Trigger Point gọi là điểm kích hoạt sự kiện, tức user chơi đến Trigger Point đó thì sẽ thấy event.

• Thời gian event được tính từ lúc user bắt đầu thấy event, và kết thúc sau X ngày cho mỗi user.

• Khi hết ngày X ngày thì user sẽ không cập nhật được điểm nữa, và sẽ có thêm Y ngày để claim phần thưởng.

• Thời gian được tính theo giờ chuẩn UTC.

• Mỗi user tham gia sẽ được phân loại vào 1 bảng xếp hạng với số lượng user được cấu hình trên CMS của GSM.

• Mỗi event có 2 loại tính điểm là: Cộng dồn điểm và Điểm cao nhất.

2.1 Lấy các events đang hoạt động

• Game gửi lên một triggerPoint và server sẽ trả về thông tin event tương ứng. (Nếu không tồn tại event thì sẽ không trả về thông tin)

• Game phải tự lưu điểm hiện tại của user tùy theo từng loại eventType

• Nếu eventType == 1 thì là loại event cộng dồn điểm

• Nếu eventType == 2 thì là loại event cập nhật điểm cao nhất

void GetEventData(string triggerPoint, Action<EventData> onEventExist, Action<long, string> errorCallback = null)

Các tham số

• triggerPoint: là mã kích hoạt mở sự kiện.

• onEventExist: Là hàm xử lý với param là dữ liệu event đang hoạt động.

• errorCallback: Hàm xử lý khi có lỗi xảy ra.

Code mẫu:

string triggerPoint = "level7"; //Đây là điểm kích hoạt mở sử kiện
GSM.Events.GSMEventProgress.GetEventData(triggerPoint, eventData =>
{
    //Tiếp tục code logic với eventData
    //Nếu eventData.eventType == 1 thì là loại event cộng dồn điểm
    //Nếu eventData.eventType == 2 thì là loại event cập nhật điểm cao nhất
});

2.2 Lấy các events đã hoàn thành

• Dùng để lấy các event đã hoàn thành sau đó sử dụng GSM.Events.GSMEventProgress.ClaimReward("{finishEventId}"); để claim phần thưởng.

• Dữ liệu phần thưởng được trả về trường reward trong mỗi đối tượng EventFinishedData

void GetFinishEvents(Action<EventFinishedData[]> onComplete, Action<long, string> errorCallback = null)

Các tham số

• onComplete: Hàm xử lý với param là mảng các event đã hoàn thành.

• errorCallback: Hàm xử lý khi có lỗi xảy ra.

Code mẫu:

GSM.Events.GSMEventProgress.GetFinishEvents(data =>
{
    foreach (GSM.Events.GSMEventProgress.EventFinishedData eventFinish in data)
    {
        // Claim an event
        GSM.Events.GSMEventProgress.ClaimReward(eventFinish.id, () =>
        {
            Debug.Log("Claim reward succeeded");
            string reward = eventFinish.reward;
            //Tiếp tục xử lý trả thưởng cho user
        }, () =>
        {
            Debug.Log("Claim reward failed");
        });
    }
});

2.3 Cập nhật điểm

• Dùng để cập nhật điểm hiện tại của user. Gửi lên khi user có sự thay đổi điểm. Điểm này cần được lưu trong dữ liệu local để tính toán chính xác.

• Ví dụ với loại event Cộng dồn điểm lần 1 user kiếm được 5 điểm, sau đó kiếm được tiếp 10 điểm thì lúc này số điểm sử dụng để cập nhật lên GSM là 15 điểm. Tức là tự phía game sẽ tính toán logic tính điểm theo từng loại event.

void UpdateScore(string eventId, int score)

Các tham số

• eventId: Id của sự kiện.

• score: Số điểm hiện tại của người chơi.

Code mẫu:

int score = 700; //Số điểm hiện tại mà client đang lưu trữ
string eventId = "648abb606bb077eb734a3099"; //Id của event đang hoạt động
GSM.Events.GSMEventProgress.UpdateScore(eventId, score);

2.4 Lấy bảng xếp hạng

• Dùng để cập nhật điểm hiện tại của user và lấy bảng xếp hạng của user.

void UpdateScoreAndGetLeaderBoard(string eventId, int score, Action<UserData[]> onComplete, Action<long, string> errorCallback = null)

Các tham số

• eventId: Id của sự kiện.

• score: Số điểm hiện tại của người chơi.

• onComplete: Là hàm xử lý với danh sách các điểm của người chơi trong bảng xếp hạng (Trong UserData có trường isSelf=true thì đó là thông tin điểm của chính người chơi đó).

• errorCallback: Hàm xử lý khi có lỗi xảy ra.

Code mẫu:

int score=700; //Số điểm hiện tại mà client đang lưu trữ
string eventId = "648abb606bb077eb734a3099"; //Id của event đang hoạt động
GSM.Events.GSMEventProgress.UpdateScoreAndGetLeaderBoard(eventId, score, response =>
{
    Debug.Log(GSM.Extension.JsonHelper.ArrayToJsonString(response));
    //Do something
});

3. Loại Leaderboard

• Là bảng xếp hạng số điểm của toàn bộ user trong 1 app

3.1 Lấy Leaderboard toàn bộ các quốc gia

• Trả về danh sách top 200 user điểm cao nhất

• Trả về thông tin tên, avatar, số điểm, và thứ hạng của user

• Nếu thứ hạng của user có rank=-1 thì tức user thuộc thứ hạng 10000+;

void GetLeaderBoardGlobal(Action<LeaderboardInfo> onComplete, Action<long, string> errorCallback = null)

Các tham số

• onComplete: Là hàm xử lý với thông tin bảng xếp hạng.

• errorCallback: Hàm xử lý khi có lỗi xảy ra.

Code mẫu:

GSMLeaderboard.GetLeaderBoardGlobal((info) =>
{
    string username=info.username; //Tên user
    string avatar=info.avatar; //avatar của user
    long score=info.score; //Số điểm của user
    int limit=info.limit; //Số lượng user tối đa được xếp hạng: ví dụ: 10000
    int rank=info.rank; //Thứ hạng của user; Nếu rank=-1 tức user có thứ hạng nằm ngoài [limit], ví dụ: 10000+
    var leaderboard= info.leaderboard; // Danh sách top 200 user
}, (statusCode, error) =>
{
    //Xử lý khi có lỗi xảy ra
});

3.2 Lấy Leaderboard theo quốc gia

• Trả về leaderboard theo quốc gia của user.

• Trả về danh sách top 200 user điểm cao nhất

• Trả về thông tin tên, avatar, số điểm, và thứ hạng của user

• Nếu thứ hạng của user có rank=-1 thì tức user thuộc thứ hạng 10000+;

void GetLeaderBoardInCountry(Action<LeaderboardInfo> onComplete, Action<long, string> errorCallback = null)

Các tham số

• onComplete: Là hàm xử lý với thông tin bảng xếp hạng.

• errorCallback: Hàm xử lý khi có lỗi xảy ra.

Code mẫu:

GSMLeaderboard.GetLeaderBoardGlobal((info) =>
{
    string username=info.username; //Tên user
    string avatar=info.avatar; //avatar của user
    long score=info.score; //Số điểm của user
    int limit=info.limit; //Số lượng user tối đa được xếp hạng: ví dụ: 10000
    int rank=info.rank; //Thứ hạng của user; Nếu rank=-1 tức user có thứ hạng nằm ngoài [limit], ví dụ: 10000+
    var leaderboard= info.leaderboard; // Danh sách top 200 user
}, (statusCode, error) =>
{
    //Xử lý khi có lỗi xảy ra
});

3.3 Cập nhật điểm của user

• Dùng để cập nhật lên điểm hiện tại của user

• Hệ thống sẽ tự đông lấy thông tin name, và avatar của user, nếu muốn thay đổi thông tin name, avatar thì dùng Set Properties

void UpdateScore(long score, Action onComplete, Action<long, string> errorCallback = null)

Các tham số

• score: Số điểm hiện tại của user.

• onComplete: Là hàm xử lý với thông tin bảng xếp hạng.

• errorCallback: Hàm xử lý khi có lỗi xảy ra.

Code mẫu:

GSMLeaderboard.UpdateScore(1000, () =>
{
    Debug.Log("Update Score Leaderboard Success");
}, (statusCode, error) =>
{
    //Xử lý khi có lỗi xảy ra
});

4. Loại Leaderboard Season

• Là bảng xếp hạng điểm của toàn bộ user trong 1 app theo 1 khoảng thời gian nhất định

4.1 Lấy các events đang hoạt động

• Dùng để xem có các event nào đang hoạt động và xử lý theo từng loại event

• Client phải tự lưu điểm hiện tại của user tùy theo từng loại eventType

• Nếu eventType == 1 thì là loại event cộng dồn điểm

• Nếu eventType == 2 thì là loại event cập nhật điểm cao nhất

void GetActiveEventsData(Action<EventData[]> onComplete, Action<long, string> errorCallback = null

Các tham số

• onComplete: Hàm xử lý với param là mảng các event đang hoạt động.

• errorCallback: Hàm xử lý khi có lỗi xảy ra.

Code mẫu:

GSM.Events.GSMLeaderboadSeason.GetActiveEventsData( events =>
{
    //Tiếp tục code logic với danh sách events
    foreach (GSM.Events.GSMLeaderboadSeason.EventData eventData in datas)
    {
        //Nếu eventData.eventType == 1 thì là loại event cộng dồn điểm
        //Nếu eventData.eventType == 2 thì là loại event cập nhật điểm cao nhất
    }
});

4.2 Lấy các events đã hoàn thành

• Dùng để lấy các event đã hoàn thành sau đó sử dụng GSM.Events.GSMLeaderboadSeason.ClaimReward("{finishEventId}"); để claim phần thưởng.

• Dữ liệu phần thưởng được trả về trường reward trong mỗi đối tượng EventFinishedData

void GetFinishEvents(Action<EventFinishedData[]> onComplete, Action<long, string> errorCallback = null)

Các tham số

• onComplete: Hàm xử lý với param là mảng các event đã hoàn thành.

• errorCallback: Hàm xử lý khi có lỗi xảy ra.

Code mẫu:

GSM.Events.GSMLeaderboadSeason.GetFinishEvents(data =>
{
    foreach (GSM.Events.GSMLeaderboadSeason.EventFinishedData eventFinish in data)
    {
        // Claim an event
        GSM.Events.GSMLeaderboadSeason.ClaimReward(eventFinish.id, () =>
        {
            Debug.Log("Claim reward succeeded");
             string reward = eventFinish.reward;
            //Tiếp tục xử lý trả thưởng cho user
        }, () =>
        {
            Debug.Log("Claim reward failed");
        });
    }
});

4.3 Cập nhật điểm

• Dùng để cập nhật điểm hiện tại của user. Gửi lên khi user có sự thay đổi điểm. Điểm này cần được lưu trong dữ liệu local để tính toán chính xác.

• Ví dụ với loại event Cộng dồn điểm lần 1 user kiếm được 5 điểm, sau đó kiếm được tiếp 10 điểm thì lúc này số điểm sử dụng để cập nhật lên GSM là 15 điểm. Tức là tự phía game sẽ tính toán logic tính điểm theo từng loại event.

void UpdateScore(string eventId, long score, Action onComplete, Action<long, string> errorCallback = null)

Các tham số

• eventId: Id của sự kiện.

• score: Số điểm hiện tại của người chơi.

• onComplete: Hàm xử lý khi cập nhật điểm thành công.

• errorCallback: Hàm xử lý khi có lỗi xảy ra.

Code mẫu:

int score = 700; //Số điểm hiện tại mà client đang lưu trữ
string eventId = "6582a8b35625e4e72e661847"; //Id của event đang hoạt động
GSM.Events.GSMLeaderboadSeason.UpdateScore(eventId, score,()={
  Debug.Log("Update Score Leaderboard Season Success");
},(statusCode, error)=>{
  // Xử lý khi có lỗi xảy ra
});

4.4 Lấy bảng xếp hạng

• Lấy bảng xếp hạng của user.

void GetLeaderBoard(string eventId, Action<LeaderboardInfo> onComplete, Action<long, string> errorCallback = null)

Các tham số

• eventId: Id của sự kiện.

• onComplete: Là hàm xử lý với thông tin Leaderboard

• errorCallback: Hàm xử lý khi có lỗi xảy ra.

Code mẫu:

string eventId = "6582a8b35625e4e72e661847"; //Id của event đang hoạt động
GSM.Events.GSMLeaderboadSeason.GetLeaderBoard(eventId, info=>
{
    string username=info.username; //Tên user, nếu bằng rỗng hoặc null chứng tỏ user chưa tham gia event
    string avatar=info.avatar; //avatar của user, nếu bằng rỗng hoặc null chứng tỏ user chưa tham gia event
    long score=info.score; //Số điểm của user, Nếu số điểm score=0 thì là user chưa cập nhật điểm, hoặc chưa tham gia event
    int limit=info.limit; //Số lượng user tối đa được xếp hạng: ví dụ: 10000
    int rank=info.rank; //Thứ hạng của user; Nếu rank=-1 tức user có thứ hạng nằm ngoài [limit], ví dụ: 10000+
    var leaderboard= info.leaderboard; // Danh sách top 200 user
});