Gifts

This module provides APIs for basic gifting of items in the app - to request for gifts, list the pending gift requests and to send a gift.

The idea is that players may sometimes be low on certain resources/items in the game - which they can request as gifts from their friends. This means that it can only be used in conjunction with a social network login - like Facebook. Eventually, we may want to remove this restriction and allow gifts to be sent and received among all users (using in-game social graph) in the game.

When a player requests for a gift, an in-app notification is sent to all the playing friends. The friends can then either decide to accept the request and give a gift or deny the request.

The application can pass custom attributes as part of the gift request - the Playblazer Platform only tracks the requests and the corresponding responses without actually looking at the contents of the request. Instead, these custom attributes are returned in the output of the List Gift Requests API call.

API: Request for gifts from friends

Request for gifts from friends API

URL: {BASE_URL}/app/<APP_ID>/gifts/<MODE>/<USER_ID>/request/new

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 String The user ID sending the gift request.
expiry No Numeric The expiry time for the gift request in seconds. If not passed, the default expiry time of 24 hrs is used.
custom:attr1 No String Set of custom attributes for
custom:attr2     the gift request. The app can decide
custom:attr3     the custom attribs to send as per the
...     situation. These are NOT used by the core platform code.
fmt No String One of (json | xml) - the format of output

The core platform code defines two hooks for gift request API - pre and post. The app-specific code can use these to implement any custom validations.

The pre hook is triggered before the gift request is saved in the DB - so, the application can throw an exception from this hook to stop the request from proceeding.

For example, assuming that the app wants to implement some quota on gift requests per user per day, it can be implemented in this hook.

The post hook is triggered after the gift request is saved in the DB.

On success, the API returns status=ok along with the request id generated.

Instead, if the requesting user’s profile is not found, it returns an error with status=error and code_str=E_NO_PROFILE. It may also return a generic error code with status=error and code_str=E_GIFT_REQUEST_FAILED if the request fails for some unknown reason.

Example

1. Successful request:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "custom:item_name=item1" \
    -F "custom:item_id=1234" \
    -F "expiry=3600" \
    "http://api.playblazer.com/v1/app/1/gifts/fb/kunalg/request/new"

Output:

{
    "status": "ok",
    "request_id": "0d0b6ed1c5904b3f88ddfa791e6e1635"
}

2. Failed request due to validation (quota exceeded):

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "custom:item_name=item2" \
    -F "custom:item_id=9876" \
    -F "expiry=3600" \
    "http://api.playblazer.com/v1/app/1/gifts/fb/kunalg/request/new"

Output:

{
    "status": "error",
    "error": {
        "message": "You have exceeded your quota of gifts",
        "code": -30004,
        "code_str": "E_GIFT_QUOTA_EXCEEDED"
    }
}

API: List gift requests

List gift requests API

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

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 whose gift requests to list.
start No Numeric The start index of gift requests - default 0. Used for pagination.
limit No Numeric The no. of entries to return in output Used for pagination.
sort No String

The sorting direction based on expiry time of the request.

Possible values:

  1. “asc” - increasing sorting order (default)
  2. “desc” - descreasing sorting order
fmt No String One of (json | xml) - the format of output

This API returns a list of gift requests the caller has received from friends.

Attention

This API call doesn’t filter out gift requests that are already expired - it just returns them as they are.

Example

URL Call:

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

Output:

{
    "status": "ok",
    "count": 2,
    "requests": [
        {
            "extra": {},
            "expiry_time": {
                "timestamp": 1383297456,
                "time_str": "2013-11-01 09:17:36 +0000"
            },
            "id": "5d4a91c0616d4c4fa1bf115adee8a60c",
            "user": {
                "lang": "it",
                "first_name": "Funky",
                "last_name": "Dude",
                    "twitterid": null,
                    "fbid": "123456",
                    "deviceid": "l",
                    "email": null,
                    "googleid": null
            }
        },
        {
            "extra": {
                "item_id": "1234",
                "item_name": "item1"
            },
            "expiry_time": {
                "timestamp": 1387531194,
                "time_str": "2013-12-20 09:19:54 +0000"
            },
            "id": "0d0b6ed1c5904b3f88ddfa791e6e1635",
            "user": {
                "first_name": "Kunal",
                "last_name": "TestHG",
                "twitterid": null,
                "fbid": "kunalg",
                "deviceid": null,
                "email": null,
                "googleid": null
            }
        }
    ]
}

API: Reply to gift request / send a gift to friend

Reply to gift request / send a gift to friend API

URL: {BASE_URL}/app/<APP_ID>/gifts/<MODE>/<USER_ID>/request/reply

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 String The user ID replying to gift request.
request_id Yes Alpha-numeric The request ID against which we’re sending a reply.
resp No String

Response type - possible values:

  1. accept - to indicate the request was accepted (default if not set)
  2. deny - to indicate the request was denied
custom:attr1 No String Set of custom attributes for
custom:attr2     the gift request. The app can decide
custom:attr3     the custom attribs to send as per the
...     situation. These are NOT used by the core platform code.
fmt No String One of (json | xml) - the format of output

Similar to the Request gift API, this API also provides the pre and the post hooks that the app-specific code can use for validations.

The core platform code only tracks the response against the given gift request ID.

On success, the output contains only status=ok.

Following errors are possible:

  1. Invalid request id - when either the request id is missing or not found in the db.

    • “status=error”, “code=-30002”, “code_str=E_GIFT_INVALID_REQUEST”

  2. The gift request has expired - we’re now past the expiry time for the given gift request.

    • “status=error”, “code=-30003”, “code_str=E_GIFT_REQUEST_EXPIRED”

Example

1. Successful reply:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "custom:item_name=item1" \
    -F "custom:item_id=1234" \
    -F "resp=accept" \
    -F "request_id=0d0b6ed1c5904b3f88ddfa791e6e1635" \
    "http://api.playblazer.com/v1/app/1/gifts/fb/abcd/request/reply"

Output:

{
    "status": "ok"
}

2. No request ID passed:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "custom:item_name=item1" \
    -F "custom:item_id=1234" \
    -F "resp=accept" \
    "http://api.playblazer.com/v1/app/1/gifts/fb/abcd/request/reply"

Output:

{
    "status": "error",
    "error": {
        "message": "Request ID not passed",
        "code": -30002,
        "code_str": "E_GIFT_INVALID_REQUEST"
    }
}

3. Invalid request ID passed:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "custom:item_name=item1" \
    -F "custom:item_id=1234" \
    -F "resp=accept" \
    -F "request_id=-1" \
    "http://api.playblazer.com/v1/app/1/gifts/fb/abcd/request/reply"

Output:

{
    "status": "error",
    "error": {
        "message": "Request with id='-1' not found",
        "code": -30002,
        "code_str": "E_GIFT_INVALID_REQUEST"
    }
}

4. Request expired:

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "custom:item_name=item1" \
    -F "custom:item_id=1234" \
    -F "resp=accept" \
    -F "request_id=5d4a91c0616d4c4fa1bf115adee8a60c" \
    "http://api.playblazer.com/v1/app/1/gifts/fb/abcd/request/reply"

Output:

{
    "status": "error",
    "error": {
        "message": "Request with id='5d4a91c0616d4c4fa1bf115adee8a60c' has expired",
        "code": -30003,
        "code_str": "E_GIFT_REQUEST_EXPIRED"
    }
}