Home
Last update : 2016-05-11
- Official Project link : https://github.com/CloudBreadProject/CloudBread
- Official Project SNS(Facebook) group : https://www.facebook.com/groups/cloudBreadProject/
- Official API reference : http://cloudbreadproject.github.io/
This document introduces CloudBread using procedure for developers. If you want to find document about install guide, refer to CloudBread install guide
CloudBread is free opensource project(MIT License) that provide almost function for mobile app and game.
Provide more than 100 Business Logic
- Mobile game developers can focused on developing mobile app
- Only call the CloudBread API adjusted parameters
- Provide example test app, Postman collection for development and test
- Do not have to make the function of calling Restful API
Construct the small~large scale of back-end server by Cloud
- Cloud's advantages use as it is, thereby develop in cloud environment.
- If server were extended, mobile game and app are not changed.
- Select the Scale-up and Scale-out are free.
- Only use the fitable game services. ( except the real time communication, deal with bulk of log data and so on... )
Provide security, administration and information of statistics
- Selectively use the Authentication and Data encryption(AES256)
- Provide GM admin tool (CloudBread-Admin-Web project)
- Provide batch for basic statistics (DAU, HAU, DARPU ...)
- Provide free tech education (Hackathon, Camp ...)
CloudBread can selectively use real time Socket server to API server(Core server). Communication between cloudBread and game client is as below. Real time communication part descript later.
- HTTP protocol
- Restful API
- JSON format
For example, check event API SelGameEvents HTTP Request structure
{
memberID = "member1"
}
SelGameEvents return to HTTP Response structure
{
EventID ="eventID1", EventName="cristal1", period=…
EventID =“"ventID2", EventName="good item1", period=…
EventID ="eventID13", EventName="bonus item", period=…
}
In CloudBread, APIs such as SelGameEvents are labeled as Behavior and give generalized APIs. In other words, API Game Logic = Behavior and Game Logic = API. So, if you add or fix the API functions, you can modify easily through framework.
CloudBread's Behavior list CloudBread support 109 Behavior on Mar 2016 basis. If refer to all of the Behavior list, go to the below link. CloudBread behavior list wiki page
CloudBread's Databases If Behavior is gamer's Action, registed Action Object is Database. For example, recored the database information as below.
| info | database table |
|---|---|
| Member | Member |
| Admin | Admin |
| Purchase | Purchase |
| Item | Item |
| Member item | MemberItem |
| Game information | GameInfo |
| Stage | Stage |
| Gift | Gift |
| Notification | Notice |
| Event | Event |
| Coupon | Coupon |
If you want to refer to CloudBread's all of database structure and detail schema info, go to the below link. CloudBread database design
CloudBread provide Server and API for Demo test to client game developers. If you want to test the API, Download the Postman included in developer preparation doc. Postman is very useful free tool for developing the REST API.
- Postman Download : Go to http://www.getpostman.com/ and Mac or Windows Chrome version download.
- API list for test in CloudBread Collection download(2016-03-26 ver)
- In Postman, click the "Import" button and apply the downloaded collection file.
- Collection tab in left side, Complete in case you find CloudBread collection.
Now, you can test CloudBread's API in DEMO server.
- Demo server address can be changed any time.
- Data is initialized periodically.
- Demo server is smallest price of cloud service. Please, only use purpose of test.
If you instgall Postman collection well, you can call the API.
- Notification inquiry - CBSelNotices API call, can check notification data.
- Event list inquiry - CBSelGameEvents API call, can check if this user can participate the event.
- Arrived gift inquiry - CBSelGiftItemToMe API call, can check the arrived gift of user.
- Member's info inquiry - CBComSelMemberGameInfoes API call, can check gamer's info.
- Member rank inquiry - GetMemberRankbyMeberID API call, can check user's rank.
- specific range ranking inquiry - GetRangeRankerInfo API call, can check a range of rank.
- First ~ xth rank inquiry - CBRank-GetTopXRanker API call, can check first~xth rank.
- Member's item list inquiry - CBSelMemberItems API call, can check gamer's item list info.
- Purchase(IAP) inquiry - CBComSelMemberItemPurchase API call, can check purchase(IAP) info.
CloudBread support 109 Behavior on Mar 2016 basis. If refer to all of the Behavior list, go to the below link. CloudBread behavior list wiki page
Postman is used for CloudBread development and test. For use of CloudBread's various API, you need example of calling API in game. You can see next chapter.
Using the famous game engine 'Unity', We introduce how to CloudBread's API call.
Project in Demo is CloudBread-Client-Unity project, and you watch the here the link.
This chapter introduce the CloudBread's DB structure and basic flow through the API.
Member fundamentally provide member's account info. Namely, Record the information of login, mail address and so on.
| MemberID | MemberPWD | Name1 | ... | |
|---|---|---|---|---|
| aaa | PWD | [email protected] | nickname a | ... |
| bbb | PWD | [email protected] | nickname b | ... |
- Since CloudBread v2.0.x, provided basic outside authentication (Facebook auth, Google ID, Microsoft ID, Kakao auth ..).
- Memberid is recorded member's characteristic id created outside authenticator.
- MemberPWD hasn't used since CloudBread v2.0.x ver. After a while, introduce the Auth handling.
- In the process of auth, if you accept the email, nickname through authorization or user input.
- Using the Postman's CBSelLoginIDDupeCheck API, check the duplication between Email and Name1.
- Email info is needed for CS or identifing user later.
- Name1 is “nickname” and used in Rank - leader board and so on.
- For insert, use the InsRegMember API.
- InsRegMember internally conduct logic that input data of Members and Gameinfo.
- Members = account, Gameinfo is used for gamer's attribute info.
- Point in Gameinfo only use number. Cuz point is used "Ranking".
- Name1's nickname and gameinfo's point are used ranking.
- CBCOMSelMember API can check member.
- CBCOMUdtMember API can modify member info.
FAQ. Where everything goes to all of the sCol in table?
- Extra column. If data have many attributes, you can store the JSON format in sCol. sCol column can store VARCHAR(MAX).
| MemberID | Level | Exp | Point | ... |
|---|---|---|---|---|
| aaa | 10 | 10000 | 100 | ... |
| bbb | 20 | 20000 | 200 | ... |
- GameInfo store the gamer's global attributes, it is different to MemberItem introduced later.
- 1:N relation. So, properties such as item store use MemberItem table.
- "carcarcar" gamer's many of the car + each car's attribute(max speed, car level and so on) -> how to store in database well?
- One car in Memberitem + Store the attribution of item in sCol1~10.
- If you lack of extra column, we will recommend for storing Json format in sCol.
- Category column utilize identifier.
- Which game money, cash item info of Gamer attribution store in 'gameinfo' or 'memberitem'?
- Recommend storing data in memberitem. Except ranking info in leader-board and gamer global info, we recommend storing memberitem.
- Gameinfo's point is only used "ranking". So, use number only.
- Name1's nickname and gameinfo's point are used ranking.
- CBComSelMemberGameInfoes API can check info.
- CBComUdtMemberGameInfoes API can modify info.
Item list table
| ItemID | ItemName | Price | Category | ... |
|---|---|---|---|---|
| GUID | item1 | 100 | consumable item | ... |
| GUID | item2 | 200 | virtual currency | ... |
- Item table store the goods of shop, game money and so on.
- Storing item list in client or server has different advantages.
- Store in server, efficiently process abusing or promotion and control game balance.
- For data storage utilization and CloudBread's API, recommend storing data in ItemList
- In CloudBread, Item = player's property. And can designate gamer's virtual currency(money).
- Pattern of storing "item" in "MemberItem" through many MemberItem behavior.
- Check all items and save client session then use through the CBSelItemListAll API.
- Check one item info through the CBComSelItemList1 API.
- In user mode, Do not add/modify item. Only admin mode can do it.
Gamer own object in game store
| MemberItemID | MemberID | ItemID | ItemCount | ItemStatus | ... |
|---|---|---|---|---|---|
| GUID | aaa | ItemList table's ItemID1 refer val | 10 | status | ... |
| GUID | aaa | ItemList table's ItemID2 refer val | 5 | status | ... |
| GUID | aaa | ItemList table's ItemID3 refer val | 3 | status | ... |
| GUID | bbb | ItemList table's ItemID1 refer val | 2 | status | ... |
| GUID | bbb | ItemList table's ItemID2 refer val | 6 | status | ... |
- Member : MemberItem = 1:N relation. This important table store gamer own item.
- "carcarcar" gamer's many of the car + each car's attribute(max speed, car level and so on) -> how to store in database well?
- One car in Memberitem + Store the attribution of item in sCol1~10.
- If you lack of extra column, we will recommend for storing Json format in sCol.
- Category column utilize identifier.
- Which game money, cash item info of Gamer attribution store in 'gameinfo' or 'memberitem'?
- Recommend storing data in memberitem. Except ranking info in leader-board and gamer global info, we recommend storing memberitem.
- If you lack of extra column, we will recommend for storing Json format in sCol.
- CBSelMemberItems API can check gamer own itmes.
- CBComSelMemberItem API can check 1 memberitme.
- CBComUdtMemberItem API can modify 1 memberitem.
- CBComInsMemberItem API can add memberitem.
- CBAddUseMemberItem API can modify membergameinfo + add/modify memberitem(transaction).
FAQ.
- INSERT or UPDATE are the reason for API Present CloudBread version handle UPSERT -> Call user's inventory already exist 'UPDATE', or not 'INSERT'. CloudBread use 1:N relation database. Of course can use UPSERT, if use attribution encryption mode, you can not use UPSERT. At the time of developing CloudBread v1, ASDB(Azure SQL Database) v11 could not provided encryption and use CLR. So, only encrypt at application(CloudBread Core) and stored in ASDB. But now, ASDB v12 can support TDE encryption. In CloudBread v3, we will change the scheme for stable process.
Gamer's playing level or phase in game
| MemberGameInfoStageID | MemberID | StageName | StageStatus | Category | Mission | ... |
|---|---|---|---|---|---|---|
| GUID | aaa | Stage1 | clear | group1 | stage mission1 | ... |
| GUID | aaa | Stage2 | clear | group2 | stage mission2 | ... |
| GUID | aaa | Stage3 | ongoing | group1 | stage mission3 | ... |
| GUID | bbb | Stage1 | clear | group1 | stage mission1 | ... |
| GUID | bbb | Stage2 ongoing | group2 | stage mission2 | ... |
- Stage means game "play unit"
- Table is 1:N relation and store effectively each stage reward, maximum score, record like Member table.
- Lack of the column utilize Json format data.
- CBSelMemberGameInfoStages API can check member's stage.
- CBComSelMemberGameInfoStages API can check one stage.
- CBComUdtMemberGameInfoStages API can modify one stage.
- CBComInsMemberGameInfoStages API can add one stage.
- CBUdtMemberGameInfoStage API can modify gameinfo and stage.
Game purchase(IAP) Table
| MemberItemPurchaseID | MemberID | ItemID | Quantity | Price | PGInfo | ... |
|---|---|---|---|---|---|---|
| GUID | aaa | Item table refer_val | 10 | 1000 | IAP company | ... |
| GUID | aaa | Item table refer_val | 1 | 5000 | IAP company | ... |
| GUID | aaa | Item table refer_val | 5 | 10000 | IAP company | ... |
| GUID | bbb | Item table refer_val | 20 | 20000 | IAP company | ... |
| GUID | bbb | Item table refer_val | 30 | 1000 | IAP company | ... |
- Purchase table store log of IAP purchase.
- Purchase means cash item purchase, and record approval info.
- Differently game item purchased game money, only store IAP purchase.
- Item purchase info record in memberitem. (in memberitem, storing virtual curreny and cash item)
- All of the purchases deal with transaction.
- CBAddMemberItemPurchase API can add item in memberitem, update gameinfo, add purchase(transaction).
- CBComSelMemberItemPurchase API can check one purchase.
- CBComUdtMemberItemPurchase API can modify one purchase.
- CBComInsMemberItemPurchase API can add one purchase.
- CBUdtReturnItem API can cancel one purchase(auto/in admin web).
Store info table that gamer can participate event
| EventID | Category | ItemID | ItemCount | Title | ... |
|---|---|---|---|---|---|
| GUID | attend reward1 | Item table refer_val | 10 | attend reward event1 | ... |
| GUID | attend reward2 | Item table refer_val | 1 | attend reward event2 | ... |
| GUID | limited period event1 | Item table refer_val | 5 | limited period event1 | ... |
| GUID | specific device user's event | Item table refer_val | 30 | specific device user's event | ... |
- Event is added in admin web page, and deal with basic list through duration.
- After login or client developer can make event through call API at any time.
- It is expressed that gamer only can join the event, and it can control duration in admin webpage
- Input the Device, OS .. info, can determin display or no in client game.
- CBSelGameEvents API can check member's joinable event
- In admin webpage, can add/modify events.
Member joined event Table
| GameEventMemberID | EventID | MemberID | ... |
|---|---|---|---|
| GUID | Event table refer_val | aaa | ... |
| GUID | Event table refer_val | aaa | ... |
| GUID | Event table refer_val | aaa | ... |
| GUID | Event table refer_val | bbb | ... |
- Because of duplicated event check, EventMember table is recorded which member can join the event or not.
- CBUdtGameEventMemberToItem API add the event in MemberItem and record it in EventMember(transaction)
Coupon list table
| CouponID | Category | ItemID | ItemCount | Status | ... |
|---|---|---|---|---|---|
| GUID | advance registration coupon1 | Item table refer_val | 10 | present status | ... |
| GUID | community open coupon | Item table refer_val | 1 | present status | ... |
| GUID | print coupon | Item table refer_val | 5 | present status | ... |
| GUID | event agency coupon | Item table refer_val | 30 | present status | ... |
-
Coupon table store coupon information also bulk of coupon.
-
Coupon and bulk of coupons can be made in admin web page.
-
Through the category info (game cafe 100 coupons, advance registration coupon), you can deliver execl files to marketing enterprise or coupon agency.
-
Coupon number is created by GUID.
-
CBCOMSelCoupon API can check the coupon's presence confirmation
Member who used coupon Table
| CouponMemberID | CouponID | MemberID | ... |
|---|---|---|---|
| GUID | Coupon table refer_val | aaa | ... |
| GUID | Coupon table refer_val | aaa | ... |
| GUID | Coupon table refer_val | aaa | ... |
| GUID | Coupon table refer_val | bbb | ... |
- Table that record member who used coupon.
- CBUdtCouponMember API can add info in memberitem, componmember. Because check which can use coupon.
- CBUdtCouponMember API can update the gamer's info attribution in gameinfo.(Please refer to Postman's CBUdtCouponMembe-GAMEINFO)
Send item, sender, receiver data record this table
| GiftID | ItemID | ItemCount | FromMemberID | ToMemberID | ... |
|---|---|---|---|---|---|
| GUID | Item table refer_val | 10 | aaa | bbb | ... |
| GUID | Item table refer_val | 5 | aaa | ccc | ... |
| GUID | Item table refer_val | 1 | bbb | ddd | ... |
| GUID | Item table refer_val | 2 | ccc | aaa | ... |
- CBSelGiftItemToMe API can check received gift.
- CBUdtMoveGift API can move a received item to memberitem(transaction).
- CBUdtSendGift API can send gift to gift box and delete memberitem(transaction).
- CBComSelGiftDepository API can check a gift.
- CBComUdtGiftDepository API can modify a gift.
Table of Processing the ranking(Rank - Leader board)
| NickName | Point | Rank | ... |
|---|---|---|---|
| Nickname a | 100 | 3 | ... |
| Nickname b | 500 | 2 | ... |
| Nickname c | 900 | 1 | ... |
- Rank is Redis_DB that memory-based NoSQL DB(basic setting)
- Execute CloudBread first time, DB store in Redis to read DB's nickname and point for synchronization.
- After synchronization, rank is added/modified by API if you need.
- CBRank-SetMemberPoint API can add/modify rank.
- GetTopXRanker API can check top x ranker list.
- GetRangeRankerInfo API can check range of member.
- GetMemberRankByID API can check this member's ranking.
- You can use auth function of Facebook, google id, Microsoft id, twitter id basically and extend auth function of Kakao.
- If member completes auth, MemberID will be changed sid automatically.
- 'sid' is characteristic value provided authenticators(facebook, and so on).
- You can test for DEMO in https://cb2-auth-demo.azurewebsites.net/ server.
- 'sid' is only saved in server. Client do not have sid, only processing the check.(only exchage x-zumo-auth token)
- If CloudBread's all of API have 'sid'(complete auth function in server), MemberID is ignored, and change to 'sid' automatically from client.
- In development step, send MemberID and available to use 'sid'.
- Authentication is separately processed CloudBread's Encryption.
- You should apply both auth and encryption for secure game communication.
- CloudBread server(Azure Mobile App - Mobile App)'s auth server construction plan
- Facebook : https://goo.gl/d0ZeQT
- Google ID : https://goo.gl/4oyM4S
- Microsoft Account : https://goo.gl/Wvn2fe
- Twitter : https://goo.gl/ZdR4qa
- Active Directory(self authentication) : https://goo.gl/WD76Ch You can construct authentication of CloudBread server(Azure Mobile App - Mobile App) through authenticator of above links.
- Manual of using authentication function in Unity - Unity coding Demo youtube
- If you need auth test using the Postman, you must be issued "x-zumo-auth"(HTTP Header) in authenticator's web site.
- For that, Windows development environment : CloudBread-Dev-Authkey-Gen-win8.1 project,
- iOS development environment : CloudBread-Dev-Authkey-Gen-Android Useing this project for issue of Authkey, you can test the request thereby inputing "x-zumo-auth" in HTTP Header.
- You can use AES256 encryption through the 'web.config' configuration.
<!-- Encryption configuration. encoding setting up -->
<add key="CloudBreadCryptSetting" value="AES256"></add>
<add key="CloudBreadCryptKey" value="1234567890123456"></add>
<add key="CloudBreadCryptIV" value="1234567890123456"></add>
- Client call the CloudBread API after conducting the encrytion.
- Delivered text of encrytion is stored in server after decoding.
- When you set-up the encrytion, server automatically responses encryted text to client.
- CloudBread-Encrypt-Text-Tool can test the text when you develop both encoding and decoding.
- You can use basic example in Postman(from the beginning 'Encrypt').
- You can test for DEMO in "https://cb2-crypt-demo.azurewebsites.net" server.
- This server is used real time communication among the gamers.
- Develop throuth the Socket.io
- Support various SDK of Android, iOS and so on(include Unity).
- Provide group
- Client request CBSocketAuth API to CloudBread for authentication.
- Token is stored in Redis cache.
- Client send the token information to Socket server.
- Socket server validate token from CloudBread and start real time communication.
- **CloudBread-Socket project**and CloudBread-Socket-React refer the project.
End of the document.
Reference link : CloudBread install guide document.
