Badges - Gamification

Badges

Badges reward users for completing a set of activity rules. A user either has a badge or does not — they are binary achievements.

7.1 Badge Entity

Rules are defined inline during badge creation (not via separate rule/create calls).

curl -X POST "$KALTURA_SCM_URL/badge/create" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Session Attendee",
    "description": "Attend 3 sessions to earn this badge",
    "virtualEventIds": ["$VIRTUAL_EVENT_ID"],
    "iconUrl": "https://example.com/badges/attendee.png",
    "participationPolicy": {"userDefaultPolicy": "display", "policies": []},
    "rules": [
      {
        "name": "Watch 3 sessions",
        "conditions": [{"fact": "eventType", "operator": "equal", "value": "viewPeriod"}],
        "type": "countUnique",
        "metric": "entryId",
        "groupBy": "kuserId",
        "goal": "3",
        "points": "1",
        "maxPoints": "1"
      }
    ]
  }'

7.2 Badge Achievement Lifecycle

1. Analytics events are evaluated against each badge's rules
2. Per-user per-rule progress is tracked in rulesData[] (each has id, progress, completed)
3. When all rules have completed: true, badge status updates to ACHIEVED with achievedTimestamp

7.3 Badge CRUD

# Get badge
curl -X POST "$KALTURA_SCM_URL/badge/get" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{"id": "'$BADGE_ID'"}'

# List badges
curl -X POST "$KALTURA_SCM_URL/badge/list" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{"pager": {"pageSize": 10, "pageIndex": 1}}'

# Delete badge
curl -X POST "$KALTURA_SCM_URL/badge/delete" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{"id": "'$BADGE_ID'"}'

7.4 User Badge Progress

curl -X POST "$KALTURA_SCM_URL/userBadge/list" \
  -H "Authorization: Bearer $KALTURA_KS" \
  -H "Content-Type: application/json" \
  -d '{"gameObjectId": "'$BADGE_ID'", "pager": {"pageSize": 100, "pageIndex": 1}}'

Response:

{
  "totalCount": 1,
  "objects": [{
    "userId": "user@example.com",
    "rulesData": [
      {"id": "rule1_id", "progress": 3, "completed": true}
    ],
    "status": "ACHIEVED",
    "achievedTimestamp": "2025-06-15T10:30:00Z"
  }]
}