Energy Management

The energy system uses the fact the “Profile Score” from the Scoring module already defines health points (hp) attribute. The health points attribute from Profile score can be used to keep track of the “health” the user currently has.

API: Ask for energy from a friend

Ask for energy from a friend API

URL: {BASE_URL}/app/<APP_ID>/energy/<MODE>/<USER_ID>/ask

Request Method: HTTP POST

Parameter Mandatory Type Description
APP_ID Yes Alpha-numeric The application ID issued by the Playblazer platform when the app was created
secret_key Yes Alpha-numeric The secret key issued by the Playblazer platform when the app was created
MODE Yes String The mode for user ID interpretation
USER_ID Yes Alpha-numeric The user ID asking for energy refill (i.e. self - who is low on energy)
from:mode Yes String The mode for user ID interpretation of user whom we’re requesting to give us energy
from:id Yes Alpha-numeric The user ID from whom we expect to receive energy. For example, a friend who already has enough energy to be able to gift us one
fmt No String One of (json | xml) - the format of output

On success, the API returns status=ok along with the request identifier for the energy request. It also internally generates an event message to the friend with event type energy_request.

Example

1. Successful request:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "from:mode=fb"  \
    -F "from:id=abcd"  \
    "http://api.playblazer.com/v1/app/1/energy/fb/kunalg/ask"

Output:

{
    "status": "ok",
    "req_id": "352f31ad6f9741da87425bf0a231cb68"
}

In the above example, user “kunalg” is asking for energy from user “abcd”.

The notification event message that is sent to the friend (“abcd”) looks something like - when retrieved via the Notifications module:

{
    "status": "ok",
    "notifications": {
        "count": 1,
        "msgs": [
            {
                "msg": null,
                "event": {
                    "type": "energy_request",
                    "event": {
                        "from": {
                            "mode": "fb",
                            "id": "kunalg"
                        },
                        "id": "352f31ad6f9741da87425bf0a231cb68"
                    }
                },
                "custom": { }
            }
        ]
    }
}

API: Grant energy to a friend

Grant energy to a friend API

URL: {BASE_URL}/app/<APP_ID>/energy/<MODE>/<USER_ID>/grant

Request Method: HTTP POST

Parameter Mandatory Type Description
APP_ID Yes Alpha-numeric The application ID issued by the Playblazer platform when the app was created
secret_key Yes Alpha-numeric The secret key issued by the Playblazer platform when the app was created
MODE Yes String The mode for user ID interpretation
USER_ID Yes Alpha-numeric The user ID granting the refill
request Yes Alpha-numeric The request ID against which the grant is issued and logged.
fmt No String One of (json | xml) - the format of output

On success, the API returns status=ok. It also internally generates an event message to the friend with event type energy_granted.

Example

1. Successful request:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "request=352f31ad6f9741da87425bf0a231cb68"  \
    "http://api.playblazer.com/v1/app/1/energy/fb/abcd/grant"

Output:

{
    "status": "ok"
}

Note

At the end of successful grant, the energy (hp) of the granter is reduced by the amount and the energy (hp) for the grantee is increased by the same amount.

As per requirements, no. of grants possible in a day is capped (default to 5). If the user tries to grant more energy requests than the capped value, an error with err_str = “E_ENERGY_MAX_COUNT_REACHED” is returned.

If the granter does not have enough energy himself, an error with err_str = “E_ENERGY_NOT_ENOUGH_ENERGY” is returned.

The notification event message sent to the grantee (“kunalg”) looks something like - when retrieved via the Notifications module:

{
    "status": "ok",
    "notifications": {
        "count": 1,
        "msgs": [
            {
                "msg": null,
                "event": {
                    "type": "energy_granted",
                    "event": {
                        "amount": 2,
                        "from": {
                            "mode": "fb",
                            "id": "abcd"
                        },
                        "id": "352f31ad6f9741da87425bf0a231cb68"
                    }
                },
                "custom": { }
            }
        ]
    }
}

API: Set Energy (for IAP energy packs)

Set Energy (for IAP energy packs) API

URL: {BASE_URL}/app/<APP_ID>/energy/<MODE>/<USER_ID>/set

Request Method: HTTP POST

Parameter Mandatory Type Description
APP_ID Yes Alpha-numeric The application ID issued by the Playblazer platform when the app was created
secret_key Yes Alpha-numeric The secret key issued by the Playblazer platform when the app was created
MODE Yes String The mode for user ID interpretation
USER_ID Yes Alpha-numeric The user ID whose energy needs to be updated.
energy Yes Numeric

The amount of energy to set. It supports the incr/decr/abs value syntax. For example,

  • energy=+8 - adds to existing value
  • energy=-3 - subtracts from existing value
  • energy=15 - sets the value
fmt No String One of (json | xml) - the format of output

On success, the API returns status=ok.

Example

1. Successful request - increment:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "energy=+15"  \
    "http://api.playblazer.com/v1/app/1/energy/fb/kunalg/set"

Output:

{
    "status": "ok"
}

2. Successful request - decrement:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "energy=-3"  \
    "http://api.playblazer.com/v1/app/1/energy/fb/kunalg/set"

Output:

{
    "status": "ok"
}

3. Successful request - set absolute value:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "energy=87"  \
    "http://api.playblazer.com/v1/app/1/energy/fb/kunalg/set"

Output:

{
    "status": "ok"
}

API: Gift energy to a friend

Gift energy to a friend API

URL: {BASE_URL}/app/<APP_ID>/energy/<MODE>/<USER_ID>/gift

Request Method: HTTP POST

Parameter Mandatory Type Description
APP_ID Yes Alpha-numeric The application ID issued by the Playblazer platform when the app was created
secret_key Yes Alpha-numeric The secret key issued by the Playblazer platform when the app was created
MODE Yes String The mode for user ID interpretation
USER_ID Yes Alpha-numeric The user ID sending the energy to a friend.
to:mode Yes String The mode for user ID interpretation of gift receiver user.
to:id Yes Alpha-numeric The user ID of the gift receiver.
fmt No String One of (json | xml) - the format of output

On success, the API returns status=ok. It also internally generates an event message to the friend with event type energy_gifted.

Note

The difference between “Grant” and “Gift” APIs is that in “Grant”, the energy of the sender is reduced by the amount that is granted.

As per requirements, no. of gifts possible in a day is capped to 50. If the user tries to gift more energy requests than the capped value, an error with err_str = “E_ENERGY_MAX_COUNT_REACHED” is returned.

Also, any user can have a max of 999 health points in the profile - beyond which, no energy gifts can be sent to the user. If a friend tries to send an energy gift to a user who already has 999 health points, the API will return an error with err_str = “E_ENERGY_FULL”

Example

1. Successful request:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "to:mode=fb"  \
    -F "to:id=abcd"  \
    "http://api.playblazer.com/v1/app/1/energy/fb/kunalg/gift"

Output:

{
    "status": "ok"
}

The notification event message that is sent to the friend (“abcd”) looks something like - when retrieved via the Notifications module:

{
    "status": "ok",
    "notifications": {
        "count": 1,
        "msgs": [
            {
                "msg": null,
                "event": {
                    "type": "energy_gifted",
                    "event": {
                        "amount": 2,
                        "from": {
                            "mode": "fb",
                            "id": "kunalg"
                        },
                        "id": "352f31ad6f9741da87425bf0a231cb68"
                    }
                },
                "custom": { }
            }
        ]
    }
}

API: List energy requests for redemption

List energy requests for redemption API

URL: {BASE_URL}/app/<APP_ID>/energy/<MODE>/<USER_ID>/list

Request Method: HTTP GET/POST

Parameter Mandatory Type Description
APP_ID Yes Alpha-numeric The application ID issued by the Playblazer platform when the app was created
secret_key Yes Alpha-numeric The secret key issued by the Playblazer platform when the app was created
MODE Yes String The mode for user ID interpretation
USER_ID Yes Alpha-numeric The user ID requesting the listing of the gifts received from friends.
fmt No String One of (json | xml) - the format of output

On success, the API returns status=ok along with the list of all the queued up energy gift receives that are eligible for redemption.

Example

1. Successful request (POST):

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    "http://api.playblazer.com/v1/app/1/energy/fb/kunalg/list"

Output:

{
    "status": "ok",
    "req_count": <no. of requests in the output>,
    "requests": [
        {
            "req_id": "<unique id of the request>",
            "sent_time": "<time the request was sent - format YYYY-MM-DD HH:MM:SS>",
            "from": {
                "fbid": "<fb ID of the sender>",
                "googleid": "<google+ ID of the sender>",
                "email": "<email of the sender>",
                "first_name": "<first name of the sender>",
                "last_name": "<last of the sender>",
                ...
            }
        },
        ...
    ]
}

2. Successful request - with no pending requests:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    "http://api.playblazer.com/v1/app/1/energy/fb/kunalg/list"

Output:

{
    "status": "ok",
    "req_count": 0,
    "requests": [
    ]
}

API: Redeem energy gifts

Redeem energy gifts API

URL: {BASE_URL}/app/<APP_ID>/energy/<MODE>/<USER_ID>/redeem

Request Method: HTTP POST

Parameter Mandatory Type Description
APP_ID Yes Alpha-numeric The application ID issued by the Playblazer platform when the app was created
secret_key Yes Alpha-numeric The secret key issued by the Playblazer platform when the app was created
MODE Yes String The mode for user ID interpretation
USER_ID Yes Alpha-numeric The user ID who is trying to redeem received energy gifts.
requests Yes JSON Array

The request IDs that should be redeemed.

Note that, the max. no. of requests that can be redeemed in one day is capped at 20.
fmt No String One of (json | xml) - the format of output

This API is used to redeem the energy gifts sent by user’s friends.

If no “requests” param is passed, the API returns an error with err_code = -70005 and err_str = ‘E_ENERGY_INVALID_REQ_ID’.

If the user has already exhausted the daily quota of redemptions (currently, 20), the API returns an error with err_code = -70007 and err_str = ‘E_ENERGY_MAX_REDEMPTION_REACHED’

Since there are multiple request IDs that are being redeemed, any or all of them may fail to redeem for some or the other reason. In such a case, the API returns “status=ok” along with the failure count - i.e. the count of how many request IDs could NOT be successfully redeemed. Each failed request ID is available in the “failed_requests” dictionary along with the reason for failure in the “error” dictionary encoded as explained for the case of “status=error”.

The output also contains the updated “profile_scores” dictionary - so that you don’t have to call the “Get Profile Scores” API again to fetch the updated HP values.

Example

1. Successful request:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "requests=[\"7282cd1a9f784885ada9168f52f6cc98\", \"92fa66190cd84d61936ea5d4067eeefc\", \"d0381cfef09144518b13e9e77a00d4d3\", \"7e027a771ebb4a949af7a9e2feaed824\", \"d6e40f98b10746498e074b4bceff1169\"]" \
    "http://api.playblazer.com/v1/app/1/energy/fb/kunalg/list"

Output:

{
    "status": "ok",
    "failed_count": 1,
    "failed_request": [
        {
            "req_id": "d0381cfef09144518b13e9e77a00d4d3",
            "error": {
                "code": -70005,
                "code_str": "E_ENERGY_INVALID_REQ_ID",
                "message": "Energy request with id='d0381cfef09144518b13e9e77a00d4d3' not found"
            }
        }
    ],
    "profile_scores": {
        "played": 124,
        "level": 6,
        "wins": 38,
        "hp": 16,
        "losses": 14,
        "rp": 1564.88,
        "xp": 0,
        "level_completion": 44.232,
    }
}

API: Get Time-to-regeneration (TTR) of energy unit

Get Time-to-regeneration (TTR) of energy unit API

URL: {BASE_URL}/app/<APP_ID>/energy/<MODE>/<USER_ID>/ttr

Request Method: HTTP GET

Parameter Mandatory Type Description
APP_ID Yes Alpha-numeric The application ID issued by the Playblazer platform when the app was created
secret_key Yes Alpha-numeric The secret key issued by the Playblazer platform when the app was created
MODE Yes String The mode for user ID interpretation
USER_ID Yes String The user ID for whom the TTR is queried.
fmt No String One of (json | xml) - the format of output

Some games may want to re-generate the energy cells for users when their health-points fall below certain threshold.

However, this re-generation rate is generally tied to the user spending some time in the game - i.e. some form of timer. Once the energy threshold is reached again, this timer can be cancelled.

Also, to keep the user engaged, we may want to display this information (i.e. the time remaining until the energy unit is generated for the user) to the user.

The no. of units to generate and the period of the timer are configurable variables as per the application’s requirements.

This API returns the time remaining until the next unit of energy is generated for the user.

If “seconds_to_regenerate” == “null” in the output, that means there is no timer active for energy regeneration.

Example

1. Successful request - when there is an active timer running for regeneration:

URL Call:

curl "http://api.playblazer.com/v1/app/1/energy/fb/kunalg/ttr?secret_key=cb8d878989b9478e96d1b1574a1bf4ec"

Output:

{
    "status": "ok",
    "seconds_to_regenerate": 522
}

2. Successful request - when there is NO active timer running:

URL Call:

curl "http://api.playblazer.com/v1/app/1/energy/fb/kunalg/ttr?secret_key=cb8d878989b9478e96d1b1574a1bf4ec"

Output:

{
    "status": "ok",
    "seconds_to_regenerate": null
}