Procedure

Procedure의 개념

Procedure는 v4 이하에서의 Item Conversion을 일반화한 개념으로, 서버에 스크립트를 등록하여, 필요한 경우 호출할 수 있다. v5 이상에서는 Javascript로 Procedure를 정의해 조건이나 반복, 산술 연산, 임시 변수, 시스템 제공 함수, 사용자 정의 함수 등을 사용할 수 있다.

##Procedure의 정의 Javascript의 function 정의 형식을 따른다. 전달하는 parameter는 Object type으로 1개를 받을 수 있다. 이 파라미터는 REST API를 호출할 때 query string으로 전달되며 복수의 key-value 쌍이 된다. procedure body 내에서는 Javascript를 이용할 수 있으며, Javascript 1.7 문법을 지원한다. 단, 일부의 제한사항이 있으며, 자세한 내용은 제한에서 다룬다.

리턴으로 지정한 변수는 REST 호출의 결과 Response에서 확인할 수 있다(call_return의 value). 리턴이 가능한 타입은 String, Number, Boolean, null, Object, Array이며 Object는 nesting이 가능하다.

Procedure 정의 Example:

function levelup_item(params) {

	// 아이템 강화 : sword + ring -> sword의 레벨증가

	var sword = HObject.load("weapon_sword", params.sword_id);

    if (sword.level<sword.max_level) {
    
        // ring 아이템은 삭제하고,
        HObject.destroy("ring", params.ring_id);

        // sword는 레벨 증가
        sword.level++;
        HObject.save(sword);  // sword의 속성이 변화됐으므로, 명시적으로 save를 해야 한다.

		return sword;
    }

}

REST API 호출 결과의 예

{
    "result_code" : 0,
    "call_return" : {
        "class": "weapon_sword",
        "id" : 342390329,
        "level" : 3
    }
}

Procedure의 호출

정의한 Procedure는 다음과 같은 방법으로 호출될 수 있다.

REST API를 사용하여 호출한다. REST API의 Procedure Call를 참조한다.
즉시 수행으로 지정된 Mission의 수행완료 API를 호출하면, 지정된 프로시저가 호출된다. 보통 이 프로시저에서는 미션의 완료조건을 검사하고, 보상을 수행하는 내용으로 구성된다. REST API의 Mission을 참조한다.
즉시 수행이 아닌 Mission의 수행완료 API를 호출하면, reward_id를 받게 되어 있는데, 이를 이용해 Reward 실행을 실행하면, 지정된 프로시저가 호출된다. 프로시저의 호출 시점만 차이가 있을 뿐 위의 경우와 유사한 내용의 프로시저가 된다. REST API의 Mission과 Reward를 을 참조한다.
Google, Apple, Naver 결제 완료 API를 호출하면 이와 연결된 프로시져가 호출된다. 보통 이 프로시저에는 결제가 완료된 후 아이템을 생성하거나 증가시키는 등의 작업을 수행하게 된다. 결제 완료와 관련된 내용은 API 문서에서 네이버 결제완료, Google 결제완료, Apple 결제완료를 참조한다.

##제공되는 라이브러리 Procedure에서 사용할 수 있도록 제공되는 Library는 다음과 같다.

HObject : Hive5 object의 생성과 삭제, 값을 읽어오거나 저장하는 함수들
HDataTable : 콘솔에서 정의한 Data Table을 Procedure에서 사용할 수 있도록 하는 함수들
HSecurity : 데이터 보안을 위한 암호화, 메세지 다이제스트(message digest) 관련 함수들
HLeaderboard : 리더보드와 관련된 함수들
HMail : Mail과 관련된 함수들
HUserLib : User Library와 관련된 함수들
HNotification : 친구 등 다른 사용자에게 메세지를 보낼 수 있는 통지와 관련된 함수들
HAppDictionary : 게임 앱 전체 사용자에게 공유되는 Dictionary
HAppCounter : 게임 앱 전체 사용자에게 공유되는 Counter
HAppQueue : 게임 앱 전체 사용자에게 공유되는 Queue
HLogger : Log 기록과 관련된 함수
HReward : Reward 관련 함수
HFriend : Friend 관련 함수
HPlayer : 사용자(Player) 관련 함수
HCoupon : Coupon 관련 함수

###1. HObject

Hive5 object의 생성과 삭제, 값을 읽어오거나 저장하는 함수들이다. Hive5 object는 Hive5 시스템에서 사용하는 데이터 구조로, C에서의 구조체나 C++, Java등에서의 클래스와 유사하다(단, 객체지향에서의 클래스가 데이터와 메소드를 지칭하지만, Hive5 object는 메소드가 지원되지 않는 데이터의 집합이라고 볼 수 있다). Hive5 object에는 javascript의 Object로 표현되며, 동적으로 필드를 추가할 수 있고 그 내용을 바꿀 수 있어서 게임과 관련된 각종 정보들을 서버에 저장하고, 각종 판정 등에 이를 사용할 수 있다.

Hive5 object는 class 이름으로 생성한다. object를 생성하면 생성된 인스턴의 id를 할당받게 되므로 클래스 이름과 id를 통해 값들을 불러오거나 업데이트하거나 소멸시킬 수 있다. 이후 Hive5 object를 object로 표현하기로 한다. Javascript의 Object와 혼동을 피하기 위해서 이는 명시적으로 Javascript Object로 지칭할 것이다.

create(className)

object를 생성할 때 사용한다. className은 ClassDescriptor에서 정의된 name이며, 해당 class의 object가 생성되어 리턴된다. ClassDescriptor에 정의되지 않은 클래스 이름이라도 사용가능하다. 이 경우에는 ClassDescriptor의 각 항목이 default로 적용된다.

Example:

var player = HObject.create("item_bomb");

destroy(className[, id])

생성된 object를 소멸시킬 때 사용한다. 소멸시킬 object의 className과 id를 넘긴다. id를 null로 하거나 id를 생략하고 className만 있다면, 싱글톤(singleton)의 모든 필드를 삭제한다는 의미다. load()도 id를 생략할 수 있는데 이 역시 싱글톤 객체를 지정하는 의미다. 싱글톤을 제외하고 생성되지 않는 객체를 소멸시키려고 하면 에러가 발생한다(Error Code 참조).

Example:

HObject.destroy("item_bomb", "12");

destroy(className, ids)

복수개의 instance를 소멸시킬 때 사용한다. ids는 소멸시킬 object id의 array다.

Example:

HObject.destroy("item_bomb", ["12", "13", "19"]);

load(className[, id])

생성된 object를 불러올 때 사용한다. 불러올 object의 className과 id를 넘기면 해당 object의 값들이 Javascript의 Object 타입으로 리턴된다. 없는 객체라면 에러가 발생한다(Error Code 참조). 싱글톤을 불러오려면 id를 null로 넘기거나 생략한다. 싱글톤 객체는 따로 생성할 필요없이 클래스 이름만으로 load하면 된다. 싱글톤 객체는 플레이어의 점수나 골드를 저장하는 등 따로 복수의 인스턴스를 생성할 필요없이 클래스 이름만으로 접근할 수 있는 경우에 사용하면 편리하며, 이와 반대로 아이템을 획득하거나 소멸시키는 경우에는 복수의 인스턴스가 필요하므로, 싱글톤이 아닌 인스턴스 생성이 더 적합하다.

Example:

var player = HObject.load("player", null);  //싱글톤
var player = HObject.load("player");  //null을 생략해도 싱글톤을 의미
var bomb = HObject.load("item_bomb", ins_id);  //create로 생성된 인스턴스

load(className, ids)

생성된 object들을 불러올 때 사용한다. 불러올 object의 className과 id들의 array를 넘기면 해당 object의 값들이 Javascript의 Array 타입으로 리턴된다. 주의할 점은 결과의 array가 ids에서 지정된 인스턴스 순서를 보장하지 않는다는 사실이다. 결과값에 인스턴스의 id도 포함되어 있으므로 이를 통해 어떤 인스턴스인지를 확인하거나, 필요하다면 특정 사용자 정의값으로 소팅해야 한다.

Example:

var items = HObject.load("item", [12231213, 1232134, 32423423]);  //create로 생성된 인스턴스의 id들

save(object)

불러온 object의 필드값들을 변경한 후, 변경 내용이 서버에 반영되도록 저장할 때 사용한다. load의 결과로 받은 객체를 넘기게 된다. 만약 이 객체의 className과 id필드를 변경하면, save 대상 객체가 바꾸어지므로 주의해야 한다. 이렇게 대상을 변경하였는데, 그 대상 객체가 없는 경우라면 에러가 발생한다.

특정 필드를 삭제하고 싶은 경우에는 그 필드를 delete 한다.

Example:

player.coin = player.coin + 1;
HObject.save(player)

delete bomb.flag;		// flag 필드를 삭제하게 됨
HObject.save(bomb)

save(objects)

objects는 object의 array다. 복수개의 object들을 동시에 save할 때 사용한다. HObject.load()와 HObject.save()가 여러 번 호출되면 수행시간이 길어지므로, array를 받는 버전을 사용하면 효율이 높아진다.

Example:

var items = HObject.load("item", [12231213, 1232134, 32423423]);  //create로 생성된 인스턴스의 id들
items = items.map(function (item) {
  item.exp = 0;
  return item;
});
HObject.save(items);

loadByPlatformUserId(platformUserid, className[, id]) (deprecated)

~~자신의 obejct가 아닌 친구나 다른 사람의 object를 불러올 수 있다. 친구의 메달 수를 조회한다거나, 친구의 인벤토리를 조회할 때 유용하다.~~

loadByUser({platform:platformName, id:userid}, className[, id])

자신의 obejct가 아닌 친구나 다른 사람의 object를 불러올 수 있다. 친구의 메달 수를 조회한다거나, 친구의 인벤토리를 조회할 때 유용하다.

Example:

var friendMedal = HObject.loadByUser({platform:"google", id:"12345"}, "medal");

loadByUser({platform:platformName, id:userid}, className, ids)

자신의 obejct가 아닌 친구나 다른 사람의 object를 불러올 수 있다. ids는 object 인스턴스 id의 Array다. 친구의 아이템들을 조회하는 등의 용도로 유용하다. 결과의 array는 ids에서 지정된 순서를 보장하지 않는다는 점을 주의해야 한다.

Example:

var friendMedal = HObject.loadByUser({platform:"google", id:"12345"}, "medal");

loadByUsers([{platform:platformName, id:userid}, ...], className)

자신의 obejct가 아닌 친구나 다른 사람들의 object를 눌러올 수 있다. 친구들 전체에 대해 이름이나, 메달 수 등을 조회할 때 유용하다. 싱글턴 객체만 불러올 수 있다.

Example:

var friendMedal = HObject.loadByUser([{platform:"google", id:"12345"}, {platform:"google", id:"12346"}], "medal");

Object 함수들을 이용한 Example

// 아이템 구매
function buy_item(params) {
    //params
    //index : 구매하려는 아이템의 고유번호(character table에 정의)
    
    // index를 갖는 아이템 인스턴스를 생성하여, 인벤토리에 저장한다.
    
    var player = HObject.load("player");
    var tbl = HDataTable.load("item", {index:parseInt(params.index)});
    
    if (tbl.length!=1)
        return "일치조건 없음";
        
    var target = tbl[0];
    
    if (player.coin<target.price)
        return "코인부족";
    
    var item = HObject.create("item");
    item.index = target.index;
    HObject.save(item);
    
    player.item_inv.push({id:item.id, index:item.index});
    player.coin -= target.price;
    HObject.save(player);
    
    return player;
}

###2. HDataTable

Hive5 콘솔에서 게임과 관련한 규칙이나 속성들을 Data Table로 저장할 수 있다. 이 테이블을 Procedure에서 사용할 수 있도록 Javascript 객체로 변환하는 함수다.

load(tableName[, condition])

콘솔에서 정의한 Data Table의 값들을 procedure에서 사용할 수 있도록 가져온다. tableName은 콘솔에서 정의한 Data Table의 이름이며, 이 테이블의 모든 값들이 Javascript의 Array로 변환하여 리턴된다. Array의 내용은 컬럼과 값들의 Object가 된다. tableName으로 지정된 Data Table이 등록되지 않았으면 에러가 발생한다(Error Code 참조).

condition은 특정 조건에 해당되는 row들만을 가져올 때 사용한다. condition은 Javascript Object로 Data table의 컬럼 이름이 key가 되고, 검색 대상의 값이 value가 된다. 복수의 조건도 가능한데 모든 조건을 만족시키는 값들이 결과가 된다. 조건에 부합하는 결과가 없다면 비어 있는 Array가 되므로, length가 0이 된다.

Example: exp_level라는 Data Table이 아래와 같이 정의되었다고 가정한다.

exp_from	exp_to	level
100	199	2
200	399	3
400	599	4
600	999	5

아래와 같이 호출하면,

var tbl = HDataTable.load("exp_level");

tbl에는 아래와 같은 Javascript 객체로 리턴받는다.

[
    {exp_from=100, exp_to=199, level=2},
    {exp_from=200, exp_to=399, level=3},
    {exp_from=400, exp_to=599, level=4},
    {exp_from=600, exp_to=999, level=5}
]

조건을 추가해서 다음과 같이 호출할 수도 있다.

var tbl = HDataTable.load("exp_level", {exp_from:200});

tbl에 들어가는 결과는 아래와 같다.

[
    {exp_from=200, exp_to=399, level=3}
]

HDataTable 사용하는 예

//경험치가 증가하여 레벨을 증가시킬 때 테이블을 참조
function increase_level_with_exp(params)

    // table 로딩
    var tbl = HDataTable.load("exp_level");

	var player = HObject.load("player");     // id가 없으면 싱글턴을 의미

    // table에서 exp범위로 찾아서 level을 세팅
    for (i=0; i<tbl.length; i++) {
        if (player.exp>=tbl[i].exp_from && player.exp<=tbl[i].exp_to) {
            player.level = tbl[i].level;
            HObject.save(player);
            break;
        }
    }

}

###3. HSecurity

데이터 보안을 위한 암호화, 메세지 다이제스트(message digest) 관련 함수들

sha1(str)

SHA-1(Secure Hash Algorithm 1) 알고리즘을 이용하여 str으로 넘긴 데이터를 변환한다.

클라이언트에서 procedure를 호출할 때 점수 등을 넘겨야 되는 경우가 있다. 이 때 점수가 평문(plaintext)이므로, 악의적으로 변조하여 보낼 경우 보안상 취약하게 되므로, sha1등의 해쉬 알고리즘을 이용하여 일련의 검정을 추가하면 보다 안전하게 전송할 수 있다.

*Examples:

//클라이언트가 프로시져를 호출할 때, score와 player의 더한 값에 대해 sha1을 수행한 check를 같이 넘긴다고 가정한다

var player = HObject.load("player");	// player 정보를 로드하고,

// 동일한 방법으로 해쉬값을 만들어 비교한다
if (params.check != HSecurity.sha1(params.score+player.exp) {
	return "invalid submit";
}

sha256(str)

SHA-256 알고리즘을 이용하여 str으로 넘긴 데이터를 변환한다.

hmacSha1(str, key, base64encoding)

HMAC-SHA1 알고리즘을 이용하여 str으로 넘긴 데이터를 key를 이용해 변환한다. base64encoding을 true로 하면 Base64 인코딩된 결과를 문자열로 받게 되며, false로 하면 hex로 표현된 문자열로 받는다.

hmacSha256(str, key, base64encoding)

HMAC-SHA256 알고리즘을 이용하여 str으로 넘긴 데이터를 key를 이용해 변환한다. base64encoding을 true로 하면 Base64 인코딩된 결과를 문자열로 받게 되며, false로 하면 hex로 표현된 문자열로 받는다.

md5(str)

MD5(Message-Digest algorithm 5) 알고리즘을 이용하여 str으로 넘긴 데이터를 변환한다.

###4. HLeaderboard

리더보드와 관련된 함수들

submitScore(leaderboardKey, score[, forceUpdate])

리더보드에 스코어를 제출할 때 사용한다. leaderboardKey는 관리콘솔에서 생성한 리더보드의 Key이며, score는 득점한 점수값이다. 리더보드 id가 유효하지 않는 경우에는 에러가 발생한다(Error Code 참조)

forceUpdate는 boolean이며, true 인 경우에, 이전 score보다 점수가 낮더라도 강제로 최고 점수로 업데이트 한다. 생략할 경우 false다.

Example:

HLeaderboard.submitScore("arena", params.score);

listGlobalScores(leaderboardKey, rankMin, rankMax[, objectClasses])

글로벌 랭킹을 조회한다. rankMin은 1부터 시작하는 순위이므로 1보다 작은 값을 전달하면 안된다. 가져올 수 있는 최대 개수는 20개여서, rankMax가 더 커도 무시된다. 값 조회 결과에 사용자들의 Object를 같이 조회하고 싶은 경우에는, string array 형태로 object의 class 이름을 objectClasses에 넣어준다.

HLeaderboard.listGlobalScores("arena", 1, 10, ["sword", "heart"]);

listGlobalScores(leaderboardKey, rankMin, rankMax, rangeMin, rangeMax[, objectClasses])

글로벌 랭킹 조회 시에 특정 점수 범위로 국한시켜서 조회한다.

listSocialScores(leaderboardKey[, objectClasses])

소셜 랭킹을 조회한다. 조회 결과에 사용자들의 Object를 같이 조회하고 싶은 경우에는, string array 형태로 object의 class 이름을 objectClasses에 넣어준다.

listGlobalScoresForLastSeason(leaderboardKey, rankMin, rankMax[, objectClasses])

지난 시즌의 글로벌 랭킹을 조회한다.

listGlobalScoresForLastSeason(leaderboardKey, rankMin, rankMax, rangeMin, rangeMax[, objectClasses])

지난 시즌의 글로벌 랭킹 조회 시에 특정 점수 범위로 국한시켜서 조회한다.

listSocialScoresForLastSeason(leaderboardKey[, objectClasses])

지난 시즌의 소셜 랭킹을 조회한다.

getMyRank(leaderboardKey)

내 등수 정보를 얻어온다. 'rank'에 자신의 등수가, 'total'에 전체 수가, 'score'에 점수가 있다. 단, 점수 기록이 없는 경우에 'rank'는 'null'이 된다.

getMyRankForLastSeason(leaderboardKey)

지난 시즌의 내 등수 정보를 얻어온다. 'rank'에 자신의 등수가, 'total'에 전체 수가, 'score'에 점수가 있다. 단, 점수 기록이 없는 경우에 'rank'는 'null'이 된다.

getInfo(leaderboardKey)

Leaderboard의 정보를 얻어온다. 결과는 다음과 같은 json이다.

{
    "id": 19876,
    "name": "Loeaderboard for test",
    "order": "larger_is_better",
    "reset_info": {
        "minute": 1,
        "hour": 1,
        "last_reset_at": "2014-07-07T01:01:00",
        "weekday": "mon",
        "period": "weekly"
    }
}

count(leaderboardKey)

현재 시즌에 점수가 등록된 총 플레이어 수를 리턴한다.

countForLastSeason(leaderboardKey)

지난 시즌에 점수가 등록된 총 플레이어 수를 리턴한다.

###5. HMail

Mail과 관련된 함수들

create(content[, tags])

메일을 생성한다. tag를 붙이고자 할때는 array 타입의 tag를 parameter로 넘긴다.

Example:

HMail.create("test mail", ["tag1", "tag2"]);

send({platform:platformName, id:user_id}, content[, tags])

친구에게 메일을 보낼 때 사용한다.

Example:

HMail.send({platform:"none", id:"1234"}, "test mail", ["tag1", "tag2"]);

count([afterId[, order[, tag]]])

메일의 개수를 얻어온다. afterId가 세팅되면 이 메일을 포함하지 않고, 다음 메일의 개수를 얻어온다. order는 asc 또는 dec이다. tag가 세팅되면 해당 tag의 메일 개수만 얻어온다.

list(limit[, afterId[, order[, tag]]])

메일 목록을 얻어온다. afterId, order, tag의 용도는 'count'에서와 같다.

delete(mailId)

id가 mailId인 메일을 삭제한다.

###6. HUserLib

User Library와 관련된 함수들

require(libName)

콘솔에서 정의한 User Library를 사용할 수 있도록 로드한다. 유저라이브러리는 javascript 기반의 함수나 global로 사용할 상수 등을 포함할 수 있다.

Example:

HUserLib.require("quest_lib");

requireOnce(libName)

콘솔에서 정의한 User Library를 사용할 수 있도록 로드한다. require()와의 차이는 동일한 라이브러리에 대해서 여러 번 호출하여도 한 번만 로드되는 것이 보장된다.

Example:

HUserLib.requireOnce("quest_lib");

###7. HNotification

친구 등 다른 사용자에게 메세지를 보낼 수 있는 통지와 관련된 함수들로 친구에게 선물하기 등을 구현할 수 있다.

send({platform:platformName, id:user_id}, type, msg)

platformName 플랫폼의 user_id를 가진 사용자에게 msg를 보낸다. type은 string으로 특정 type만 receive할 수 있도록 지정할 수 있다. msg는 javascript Object 형식으로 실제 내용이다.

*example:

// 선물하기 메세지를 보내는 예
HNotification.send({platform:"none", id:"1234"}, "gift", {type:"gift", param1:"heart", param2:"1"});

receiveAll()

자신에게 온 msg를 모두 수신한다. send를 통해 보내진 javascript Object들의 Array형태로 리턴받는다. 한 번 수신을 하면 삭제되므로, receiveAll()을 다시 호출하면 이미 수신한 메세지는 더이상 포함되지 않는다. send()에서 파라미터로 넘긴 type은 따로 리턴되지 않으므로, 분류가 필요한 경우에는 아래의 예처럼 메세지의 필드를 이용해야 한다.

*example:

// 수신 메세지에서 선물하기를 받았는지 확인하고 하트 증가
var msgs = HNotification.receiveAll();
for (var i=0; i<msgs.length; i++) {
	var msg = msgs[i];
    if (msg.type=="gift") {
    	if (msg.param1 =="heart") {
            var user = HObject.load("user");
            user.heart += msg.param2;
            HObject.save(user);
        }
    }
}

receive(type)

send()때 지정한 type을 갖는 메세지만 모두 수신한다.

###8. HAppDictionary

게임 앱 전체 사용자에게 공유되는 Dictionary다. 앱당 사용 가능한 개수는 10개이며, 관리 콘솔에서 추가, 삭제할 수 있다.

get(key)

해당 key의 value를 가져온다.

set(key, value)

해당 key의 value를 세팅한다.

exist(key)

해당 key가 존재하는지를 boolean으로 리턴받는다.

주의

HAppDictionary를 사용할 때 주의할 점이 있다. 다음과 같이 get으로 읽어들인 문자열의 뒤에 덧붙여 set을 한다고 가정하자.

var nicknameList = HAppDictionary.get("nicks");		// (1)
HAppDictionary.set("nicks", "|"+userNickname);		// (2)

userNickname이 melon인 사용자A가 이 프로시저가 호출하는 경우를 고려해 보자. (1)이 실행될 때 nicknameList가 "apple|orange"라고 가정하자. (2)가 실행되면 melon이 덧붙여져서 "apple|orange|melon"으로 세팅될 것이다. 그러나, userNickname이 mango인 다른 사용자 B가 동일한 프로시저를 호출했을 때, 실행 시점의 문제로 melon이 증발해버릴 수 있다. 즉, 사용자B의 (1)은 사용자 A의 (1)전에 실행이 되었고, (2)는 반대로 사용자 A의 (2)이후에 실행되었다면, nicks의 결과는 "apple|orange|mango"가 되어버린다.

결론적으로, get과 set을 동시에 수행할 때, 실행 시점의 문제로 동기화가 완전하게 보장되지는 않으므로, 동기화가 중요하지 않은 곳에 사용해야 한다. 동기화가 중요한 문제라면, 용도에 따라 HAppCounter나 HAppQueue를 사용해야 한다.

###9. HAppCounter

게임 앱 전체 사용자에게 공유되는 Counter. 게임 내에서 선착순 n명에게 보상을 지급하는 이벤트 등에 유용하다. 사용가능한 카운터의 개수는 앱당 10개로 제한되며, 관리 콘솔에서 추가, 삭제할 수 있다.

increase(counterName)

해당 이름을 가진 카운터를 1 증가시킨다. 리턴 값으로 변경된 값을 받는다. 없는 카운트 이름이면 0의 초기값을 갖는 카운터를 새로 생성한 후 증가된다.

increaseBy(counterName, increment)

해당 이름을 가진 카운터를 increment 만큼 증가시킨다. 리턴 값으로 변경된 값을 받는다. 없는 카운트 이름이면 0의 초기값을 갖는 카운터를 새로 생성한 후 증가된다.

decrease(counterName)

해당 이름을 가진 카운터를 1 감소시킨다. 리턴 값으로 변경된 값을 받는다. 없는 카운트 이름이면 0의 초기값을 갖는 카운터를 새로 생성한 후 증가된다.

decreaseBy(counterName, decrement)

해당 이름을 가진 카운터를 decrement 만큼 감소시킨다. 리턴 값으로 변경된 값을 받는다. 없는 카운트 이름이면 0의 초기값을 갖는 카운터를 새로 생성한 후 증가된다.

get(counterName)

해당 이름을 가진 카운터의 현재 값을 가져온다.

HAppCounter를 사용하는 예

// 선착순 100명에게 보상
var count = HAppCounter.increase("dungeon_event1");
if (count<=100) {
	// 보상을 수행함
    var user = HObject.load("user");
    user.gold += 100;
    HObject.save(user); 
    return {reward:true, msg:count+"번 째로 입장하여 선착순 100명 미션을 달성하셨습니다! 100골드를 지급합니다."};
}
else {
    return {reward:false, msg:count+"번 째로 입장하여 선착순 100명 미션 달성에 실패했습니다."};
}

###10. HAppQueue

게임 앱 전체 사용자에게 공유되는 Queue다. 앱당 사용 가능한 큐의 개수는 10개이며, 관리 콘솔에서 추가, 삭제할 수 있다.

enqueue(queueName, data)

이름이 queueName인 큐에 data를 넣는다. data는 javascript Object 객체다. 없는 큐 이름이면, 새로 생성한다.

dequeue(queueName)

이름이 queueName인 큐에서 꺼내와 리턴받는다. 더이상 꺼내올 데이터가 없다면, null을 리턴받는다.

###11. HLogger

Log 기록과 관련된 함수

log(msgType, msg)

플레이어별로 로그를 기록할 수 있다. 콘솔에서 플레이어별로 기록된 로그의 열람이 가능하며, msgType으로 필터링이 가능하다. 아이템 구매 내역 기록 등의 용도로 유용하다.

*Example:

HLogger.log("items", "황금폭탄 구매(590gold)");

list([msgType, ] offset, limit)

로그를 조회한다. internal에서만 불리운다.

count([msgType])

로그의 개수를 세어온다.

###12. HReward

Reward와 관련된 함수

create({platform:platformName, id:user_id}, procedureName, procedureParams[,mailContent])

reward를 생성한다. platformName 플랫폼의 user_id를 가진 사용자에게 reward가 생성되는데, 현재 플레이어에게 생성하려면 미리 선언된 상수 'ME'를 사용한다. number type의 reward id가 리턴된다.

*Example:

var rewardId = HReward.create(ME, "procedure1", {"p1": "a", "p2":"b"}, "보상이 지급되었어요!");
var rewardId2 = HReward.create({platform:"none", id:"12345"}, "procedure1", {"p1": "a", "p2":"b"}, "보상이 지급되었어요!");

invalidate(rewardId[,deleteMail])

reward를 무효화한다. rewardId는 create의 결과로 리턴된 id이며, deleteMail을 true로 하면, create때 생선된 메일까지 삭제한다.

*Example:

HReward.create(ME, "procedure1", {"p1": "a", "p2":"b"}, "보상이 지급되었어요!");
HReward.create({platform:"none", id:"12345"}, "procedure1", {"p1": "a", "p2":"b"}, "보상이 지급되었어요!");

invalidateByRules(expirationDay, maxCapacity, deleteMail)

규칙에 의해 reward를 무효화한다. expirationDay는 보관 일수로 7을 전달하면 시간까지 고려하여 최근 7일간 받은 보상을 보관하고 그 이전의 것을 무효화한다. maxCapacity는 최대 보관 개수로 100을 넘기면 최근 100개만 남기고 나머지는 무효화한다. deleteMail은 reward와 연계된 메일까지 삭제할 때 true를 넘긴다. expirationDay가 maxCapacity보다 우선 적용된다. 삭제된 항목이 하나라도 있으면 true를 리턴하고 그렇지 않으면 false를 리턴한다.

*Example:

// 7일 이전의 메일과 reward를 삭제하며, 최근 50개 보다 오래된 것들도 삭제한다.
HReward.invalidateByRules(7, 50, true);

###13. HFriend

Friend와 관련된 함수

list([group])

친구들의 목록을 조회한다. 특정 그룹의 친구를 조회하고자 하는 경우에는 그룹의 이름을 parameter로 넘겨준다.

*Example:

HFriend.list();

####~~update(group, friends)~~ (deprecated) ~~특정 그룹 'group'의 친구목록을 'friends'로 교체한다. friends는 platform_user_id(string)의 array이다.~~

update(group, platform, friends)

특정 그룹 'group'의 친구목록을 'friends'로 교체한다. friends는 platform_user_id(string)의 array이고, platform은 이들이 속한 platform이다.

*Example:

HFriend.update('default', 'kakao', ['1235d23e', 'xxdf1232123']);

####~~add(group, friends)~~ (deprecated) ~~특정 그룹 'group'의 친구목록에 'friends'를 추가한다. friends는 platform_user_id(string)의 array이다.~~

add(group, platform, friends)

특정 그룹 'group'의 친구목록에 'friends'를 추가한다. friends는 platform_user_id(string)의 array이고, platform은 이들이 속한 platform이다.

*Example:

HFriend.add('default', 'kakao', ['1235d23e', 'xxdf1232123']);

addSymmetrically(group, platfrom, friend[, maxFriendSize])

특정 그룹 'group'에 friend를 추가한다. 이때, 서로 친구가 되도록 한다. friend는 platform_user_id(string)이다. 이미 그룹에 maxFriendSize 만큼의 친구가 둘 중 한명이라도 있게되면 exception이 발생한다. exception은 TooManyFriendsException이고, error code는 2705이다.

####~~remove(group, friends)~~ (deprecated) ~~특정 그룹 'group'의 친구목록에서 'friends'를 삭제한다. friends는 platform_user_id(string)의 array이다.~~

remove(group, platform, friends)

특정 그룹 'group'의 친구목록에서 'friends'를 삭제한다. friends는 platform_user_id(string)의 array이고, platform은 이들이 속한 platform이다.

*Example:

HFriend.remove('default', 'kakao', ['1235d23e', 'xxdf1232123']);

removeSymmetrically(group, platform, friend)

상호 친구 관계를 삭제한다.

count([group])

친구 수를 센다. group을 설정하면 해당 group내의 친구만 센다.

count({platform:platform, id:id}, [group])

특정 player의 친구 수를 센다. group을 설정하면 해당 group내의 친구만 센다.

###14. HPlayer

Player와 관련된 함수

findByNickname(nickname)

nickname으로 player를 찾는다. 결과로 "platform"과 "id"가 포함된다.

*Example:

HPlayer.findByickname('nickname_1');

###15. HCoupon

Coupon과 관련된 함수

get(serial)

serial로 발급된 쿠폰 정보를 얻어온다. 다음 항목이 결과에 포함된다. campaign_id, serial, valid_from, valid_to

invalidate(serial)

serial로 발급된 쿠폰을 무효화한다. 무효화를 할때는, 쿠폰과 연계된 'call'을 실행시키지 않는다.

Procedure에서 발생하는 Error

프로시저와 관련된 에러는 크게 Javascript 내에서 일어나는 Runtime 에러와 Hive5의 Library나 구조에서 발생되는 에러가 있다.

1. Javascript script에서 발생하는 exception

Javascript에서 exception이 발생되면 결과의 result_code가 3001이며, 내용은 result_message에 표시된다. 구문 오류나 null 객체에 대한 인덱스 접근 등이 이에 해당한다. Javascript에서 exception을 throw해도 3001 코드가 리턴되므로, 디버킹 용도로 사용할 수 있다. 다음은 throw를 사용하는 예다

if (player.coin < 0)
	throw("coin is less than 0");

만약 if내의 조건이 참이어서 throw가 실행된다면 response는 다음과 같을 것이다.

{
	"result_code" : "3001",
    "result_message" : "coin is less than 0"
}

###2. 그 외의 에러 제공되는 라이브러리나, Hive5 REST API와 연관된 에러들은 Error Code에 정의되어 있다. ClassDescriptor에서 Event Handler로 지정한 프로시저가 없다면, load때 다음과 같은 결과를 얻을 것이다.

{
	"result_code" : "3101",
    "result_message" : "Procedure Not Found"
}

Error Code

API 문서의 error code 참고

##제한

1. Array type에서의 key 제한

Hive5 object의 필드를 Array로 선언했으면, 문자열의 키를 사용할 수 없다.

var player = HObject.load("player");
player.items = new Array();
player.items["type"] = "weapons";	// array인 필드에 문자열 키를 사용할 수 없다.
HObject.save(player); 	// 에러 발생함

Hive5 object의 필드가 Javascript의 Object인 경우에는 숫자형 키가 사용가능하다. 단 이 경우 실제 Array는 아니므로, length는 0이다.

var player = HObject.load("player");
player.missions = new Object();
player.missions[0] = "level_mission";	// object인 필드에 숫자형 키를 사용할 수 있다.
player.missions[1] = "score_mission";
HObject.save(player);

2. Return의 제한

리턴 타입으로는 Number, String, Boolean, null, Array, Object가 가능하다. Object는 nesting이 가능하다. function을 리턴할 경우 에러가 발생한다. Number type인 경우에도 NaN이나 Infinity를 리턴할 경우 에러가 발생한다.

3. 환경의 제한

수행시간은 다음과 같은 제한이 있다.

수행시간: 1000 ms 까지 허용

API

Procedure Call

Path: /:version/procedures/call/:name
Authentication Header: X-APP-KEY, X-AUTH-UUID, X-AUTH-TOKEN
Method: POST
Request Parameter:

Name Type Description

name String procedure name

procedure에 전달할 parameter는 json의 body 형태로 정의한다.

js''' { param1:"aaa", param2:"bbb"}


이렇게 넘겨진 parameter는 프로시저 내에서는 Javascript Object 타입인 params의 key, value 형태로 전달된다. 위 호출의 경우에는 params가 다음과 같은 값을 가지게 된다.

```js
{ param1:"aaa", param2:"bbb"}

즉, params.param1 또는 params.param2의 형태로 사용한다.

Response Body: JSON

Name	Type	Description
result_code	Number	Error Code 참고
result_message	Option[String]	실패한 경우에 메시지 있을 수 있음
call_return	Null/String/Number/JSON Object	procedure call의 결과. call을 정의하는 것에 따라서 이 값의 type도 변경되니 유의

Procedure Call (no authentication)

player 인증 전에 procedure call이 필요할 때 사용합니다.

Path: /:version/procedures/check/:name
Authentication Header: X-APP-KEY, X-AUTH-UUID
Method: POST
Request Parameter:

Name Type Description

name String procedure name