Invite Tracking¶

The invites module exposes an API for tracking the invites sent by the application.

Each invite tracked is identified by a tracking ID. However, there is not much the application needs to do about the tracked invite.

The tracking works across different modes - including the social graphs. The application just submits the receiver user’s information in the same format as (mode, uid) - where mode could be one of ‘fb’, ‘google’, ‘phone’ or ‘email’. These are the same as the ones used for user identity.

When the invited user joins the application, Playblazer will automatically inform the users that sent the invite to the newly-joined user.

Important

We can only track invited users who create profiles using the same (mode, uid) as submitted by the application for tracking in the invites.

API: Track invites sent by application¶

Track invites sent by the application using external invitation mechanism.

URL: {BASE_URL}/app/<APP_ID>/invites/<MODE>/<USER_ID>/track

Request Method: HTTP POST

Required HTTP Header: Content-Type: application/json

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 invite.
to	Yes	JSON Array	The list of entries indicating users who have been invited. Details explained below.
fmt	No	String	One of (json \| xml) - the format of output

On successful execution, the output will carry list of trackings generated along with status=ok.

The output will also contain a list (possibly empty) of entries - already_invited - for users who have already been invited and have the invite in “pending” state. The format of entries will be as provided in the input.

Each entry in the “to” array has the following fields:

mode (mandatory)

id (mandatory)

first_name (optional)

last_name (optional)

Each entry in the input must contain at least “mode” and “id” keys. You can include additional optional keys - like “first_name”, “last_name”. However, also including “first_name” and/or “last_name” will be beneficial. These will be carried in the “extra_data” part of the invite.

Attention

Please ensure that each entry in the “to” array contains properly URL-encoded strings ONLY.

When an invited user joins the app, the users who had invited that user will get notified with the following notification format (subject to change):

{
    "msg": "new_user_joined",
    "custom": {
        "user": {
            "attribs": {
                "first_name": "Nikhil",
                "last_name": "Soman",
                "twitterid": null,
                "fbid": "xxxxxxxxxxxxxxxx",
                "deviceid": null,
                "googleid": null
            }
        }
    }
}

The notification will be available both in the in-app queue as well as push channels (subject to user having registered for push notification).

Example¶

URL Call:

Note

The “to” parameter is split into multiple lines for better readability. It’s actually one single line when passed on command line.

curl -X POST \
    -H "Content-Type: application/json" \
    -d "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -d "to=[ { \"mode\": \"phone\", \"id\": \"%2B911234567890\",
                \"first_name\":\"Invitee\", \"last_name\": \"1\"},
             { \"mode\": \"email\", \"id\": \"user%40example%2Ecom\",
                \"first_name\": \"Invitee\", \"last_name\": \"2\"},
             { \"mode\": \"email\", \"id\":\"another_user%40example%2Ecom\",
                \"first_name\": \"Invitee\", \"last_name\": \"3\"}
           ]"   \
    "http://api.playblazer.com/v1/app/1/invites/fb/kunalg/track"

Output:

{
    "status": "ok",
    "new_invites": [
        {
            "completion_time": null,
            "extra_data": {
                "first_name": "Invitee",
                "last_name": "1"
            },
            "invite_id": "bfc8625d-570f-499b-ab1b-ebfce531fa90",
            "sent_time": "2014-09-09 09:21:33 +0000"
        },
        {
            "completion_time": null,
            "extra_data": {
                "first_name": "Invitee",
                "last_name": "2"
            },
            "invite_id": "000f5f26-4848-4bbc-a03c-6bf276f67b59",
            "sent_time": "2014-09-09 09:21:33 +0000"
        },
        {
            "completion_time": null,
            "extra_data": {
                "first_name": "Invitee",
                "last_name": "3"
            },
            "invite_id": "85c2a48d-ce15-40b9-9e39-c89c7a0302d3",
            "sent_time": "2014-09-09 09:21:33 +0000"
        }
    ],
    "already_invited": [
    ]
}