Gamify Livestreams - distribute badges to attendees while they watch your event's live stream on your website.
APACHE-2.0 License
OMG badges is an open-source gamification framework for distributing badges to attendees while watching your event's live stream. This app was built for https://dscomg.com and now is open to all communities to utilise in their own meetup/event/etc.
What does OMG badges do?
Documentation is hard. I have tried my best to list everything in detail but please feel free to ask any questions in the issues.
NOTE: This application relies on "Google-Sign-In" for authorization. The JWT token granted by Google is exchanged for a native access token which also signs up the user here and gets their identity. The access token is then used as a Bearer token to interact with the application. So, your client must support Google sign-in. It's easy, read on :)
python -m venv env
source env\Scripts\activate
source env/bin/activate
pip install -r requirements.txt
.env
and copy contents of .env_dummy
to .env
in the same directorySECRET_KEY=
DB_NAME=
DB_USER=
DB_PASSWORD=
DB_HOST=
DB_PORT=
GOOGLE_OAUTH2_KEY=
GOOGLE_OAUTH2_SECRET=
PRODUCTION=
PRODUCTION=False
during development in .env
file otherwise enter the db details. If you wish to use SQLite3 for production db, in that case also leave PRODUCTION=False
and ignore any other DB_* fields. Keep in mind that the app will run in debug mode if PRODUCTION=False
.read more about Google auth here - https://developers.google.com/identity/protocols/oauth2
Make sure to not have give spaces between KEY=VALUE
After the above setup, run
python manage.py makemigrations
python manage.py migrate
python manage.py createsuperuser
make sure to enter all the details including email
python manage.py runserver
Runs the backend server at default port 8000
.
Open http://localhost:8000 to view it in the browser.
You can use the badges in 2 ways
This is used to provide badges when a user attends a set number of sessions. eg- Attended 5 sessions, Attended 20 sessions.
POST /api/auth/convert-token
Parameter | Type | Value | Description |
---|---|---|---|
grant_type |
string |
convert_token |
as it is |
client_id |
string |
<Django-Oauth-Client-ID> |
Copied previously |
backend |
string |
google-oauth2 |
as it is |
token |
string |
<Google-Auth-Access-Token> |
Obtained when client side signin using Google Oauth2 API |
example:
{
"grant_type": "convert_token",
"client_id": "hse8AgZkiHdVcGGtVRB3sbuW4w4DM46UA78fI50P",
"backend": "google-oauth2",
"token": "ya29.a0AfH6SMDnFAX_ZKMJNzv4CmVbQbWYCp6PLavVdfOzaJEGHjAaoOxN86UUXLyic_a1ZMJRqVJxd1t5IkGjdVPlnZxwWPJUrRF2TujZISkwDV2iFQtzsEfUMYsdcWt0hJ8Pk1wvNugf-QwZs0jUlg8rdgp_PYCcMyI_7R4"
}
Response
{
"access_token": "Jd4hNC3qjljlzTBMSkdf97x0iOy5Fu",
"expires_in": 36000,
"token_type": "Bearer",
"scope": "read write",
"refresh_token": "Fcp6VflwUrrX65gxJ0qKnfxgYa1Q6a"
}
Save the access_token at the client and use the access token in the header for each authorized request. Note You will receive a new access_token EACH TIME you login on the client and send request to this API. Make sure to overwrite the access_token with the fresh one every time. Or use the refresh token to get a new token after expiration. Feel free to send a PR to this documentation explaining that.
POST /api/session
Set this as the header of the request
Authorization: Bearer <access-token>
Parameter | Type | Value | Description |
---|---|---|---|
track |
integer |
<track-value> |
send the track number of session/default 1 |
example:
{
"track": 1
}
Response
{
"user": "[email protected]",
"success": true,
"badgeEarned": false
}
badgeEarned
parameter will be True/False depending on
GET /api/session
Set this as the header of the request
Authorization: Bearer <access-token>
Response
{
"sessions": [
{
"sessionId": "D01S01",
"name": "Keynote on ML",
"start": "2020-07-04T16:44:25+05:30",
"end": "2020-07-05T16:44:26+05:30"
}
],
"uuid": "6179ea9a-363f-4d1f-a597-07715b612c2e"
}
uuid
is returned on every get call session/badges. This UUID can be used to anonymously fetch the public profile of the user.
POST /api/badges
Set this as the header of the request
Authorization: Bearer <access-token>
Parameter | Type | Value | Description |
---|---|---|---|
badge |
string |
<badge-id> |
send badge ID |
example:
{
"badge":"secretBadge1"
}
Response
{
"user": "[email protected]",
"success": true,
"badgeEarned": false,
"badge": "secretBadge1"
}
This route can be used to grant badges which are not attached to any particular sessions but are present independently.
GET /api/session
Set this as the header of the request
Authorization: Bearer <access-token>
Response
{
"badges": [
{
"badgeId": "D01S01badge",
"name": "Watched ML Keynote",
"image": "/media/badge/lAWQtaCV_400x400_pOV3u2h.jpg"
},
{
"badgeId": "D01S02badge",
"name": "ML Overlord!",
"image": "/media/badge/lAWQtaCP_400x400_pOV3u2g.jpg"
}
],
"uuid": "6179ea9a-363f-4d1f-a597-07715b612c2e"
}
uuid
is returned on every get call session/badges. This UUID can be used to anonymously fetch the public profile of the user.
GET /api/session/collection/<uuid>
GET /api/badges/collection/<uuid>
No Auth needed
Response
{
"badges": [
{
"badgeId": "D01S01badge",
"name": "Watched ML Keynote",
"image": "/media/badge/lAWQtaCV_400x400_pOV3u2h.jpg"
},
{
"badgeId": "D01S02badge",
"name": "ML Overlord!",
"image": "/media/badge/lAWQtaCP_400x400_pOV3u2g.jpg"
}
],
"email": "kau*****@gmail.com"
}
email
is returned in an obscured fashion. This link can be shared by the users on social media and people can visit this link to view the user's badges.
This application was deployed on DigitalOcean for use during our event. You can follow this article for setup and deployments, this should work the same for any cloud service.
Each time a user logs in a new access_token
and refresh_token
is created in the database. They grow to a huge number and takes a lot of space. It's recommended to delete all the tokens from time to time.
If anyone has any solution to this issue (solution - Automatically delete old tokens when new tokens are created) please feel free to fix it and send a PR here. This app depends on rest-framework-social-oauth2 for oauth2.
HAVE LOTS OF FUN WHILE HOSTING YOUR NEXT eMEETUP!! ⭐️ this project if you like it :D
Follow me on twitter for more!