OEngage v1.0.0

Requirements

Single user view

Click any user row to open a full profile card: XP, level, streak, level progress bar, profile completeness. From this view admins can award XP (amount + reason), award a badge from a dropdown, view earned badges grid, see recent activity, manage active sessions, impersonate the user, or delete the account.

Page assignments

Authentication features

Registration

Utility bar

AJAX actions

OAuth callback URL

https://yoursite.com/?or_oauth_callback={provider}
// provider = google | github | linkedin | apple

Email already exists

If the email from a social provider already exists as a WP user: OEngage logs in that user automatically (no error), stores the provider's user ID in user meta (oe_social_google, etc.), and sends a "Social login added" notification email.

TOTP (Google Authenticator)

• Standard RFC 6238 TOTP — compatible with Google Authenticator, Authy, 1Password
• Pure PHP implementation — no external library dependency
• 32-character base32 secret stored per user in or_2fa table
• ±1 code window (30-second tolerance)

Email code

6-digit numeric code sent to user's email address. 10-minute expiry via WordPress transient.

Setup flow (user-side)

Default registration fields

Fields configured in wp_options key oe_registration_fields. Custom fields can be added programmatically or via a future admin UI.

User meta keys

Profile completeness & privacy

ProfileRepository::get_completeness() returns 0–100% based on four checks: display name set, bio filled in, custom avatar uploaded, email verified. Prompts shown on dashboard if < 100%.

Default XP actions

Daily login XP is only awarded once per calendar day, checked via oe_last_xp_login user meta.

Default levels

Level names and XP thresholds are fully configurable in Gamification → Levels.

Streak system

StreakEngine::record_login() is called on every successful login. Streak increments if last login was yesterday; resets to 1 if the gap is more than 1 day. Longest streak is tracked separately in oe_longest_streak user meta.

Template variables

Template-specific extras: verify_email → {{verify_link}} · password_reset → {{reset_link}} · magic_link → {{magic_link}} · 2fa_code → {{code}} · social_connected → {{provider}}

Follow system

Users can follow/unfollow each other. Relationships stored in or_follows. Follow button appears on other users' profile pages. Following awards XP (follow_user action). Followed user receives a new_follower notification. Follower/following counts shown on profile stats bar.

Direct messaging

Basic user-to-user messaging via or_messages.

GET /profile/{user_id}

Returns a user's public profile data. Returns 403 if profile is private, 404 if user not found. Email is never returned for privacy.

JSON{
  "user_id":      42,
  "display_name": "Jane Doe",
  "bio":          "WordPress developer",
  "avatar_url":   "https://example.com/wp-content/uploads/avatar.jpg",
  "total_xp":     1500,
  "level":        5,
  "login_streak": 7,
  "privacy":      "public",
  "registered":   "2024-01-15 10:30:00",
  "last_active":  "2025-04-20 14:22:00"
}

GET /leaderboard

Returns top users by XP. Query params: ?type=xp · ?limit=1-50 (default 10).

JSON[
  {
    "rank":         1,
    "user_id":      42,
    "display_name": "Jane Doe",
    "avatar_url":   "...",
    "value":        12500,
    "level":        "Legend"
  }
]

GET /user/{user_id}/xp

Returns XP and level data for a user.

JSON{
  "level":          5,
  "level_name":     "Veteran",
  "total_xp":       1500,
  "next_threshold": 3000,
  "progress":       53
}

Action hooks

PHP// After user registers (before email verification)
do_action( 'oengage_user_registered', $user_id );

// After successful login
do_action( 'oengage_login', $user_id );

// When XP is awarded
do_action( 'oengage_xp_awarded', $user_id, $amount, $action );

// When a badge is earned
do_action( 'oengage_badge_earned', $user_id, $badge_id );

// When a user follows another
do_action( 'oengage_user_followed', $follower_id, $following_id );

// When a streak is updated
do_action( 'oengage_streak_updated', $user_id, $current_streak );

// When a direct message is sent
do_action( 'oengage_message_sent', $sender_id, $receiver_id );

// When a user's profile is updated
do_action( 'oengage_profile_updated', $user_id );

Usage examples

PHP// Slack notification on registration
add_action( 'oengage_user_registered', function( $user_id ) {
    $user = get_userdata( $user_id );
    // ... send Slack notification
} );

// Award XP on WooCommerce order completion
add_action( 'woocommerce_order_status_completed', function( $order_id ) {
    $order   = wc_get_order( $order_id );
    $user_id = $order->get_user_id();
    if ( $user_id ) {
        \OEngage\Gamification\XPEngine::award( $user_id, 100, 'woo_purchase' );
    }
} );

// Custom logic when a badge is earned
add_action( 'oengage_badge_earned', function( $user_id, $badge_id ) {
    // Webhook, push notification, etc.
}, 10, 2 );