NativePHP Play Games Services#

Add Google Play Games Services — sign-in, leaderboards, and achievements — to your NativePHP Mobile Android app in minutes. No Kotlin, no Gradle edits.

Works with any frontend — Livewire, React, Vue, Alpine.js, or plain JavaScript.

Android only. Play Games Services is a Google Play platform feature — it doesn't exist on iOS. For an equivalent iOS experience, see game-center.

Requirements#

PHP 8.2+
Laravel 12+
NativePHP Mobile 3.x or 4.x
A Play Console app with Play Games Services configured (App ID, leaderboards, achievements)

Installation#

1. Install the package#

Copied!

composer require bhargavdetroja/nativephp-play-games-services
php artisan native:plugin:register bhargavdetroja/nativephp-play-games-services

composer require bhargavdetroja/nativephp-play-games-services
php artisan native:plugin:register bhargavdetroja/nativephp-play-games-services

2. Publish the config#

Copied!

php artisan vendor:publish --tag=play-games-services-config

php artisan vendor:publish --tag=play-games-services-config

3. Add your Play Games App ID to `.env`#

Copied!

# Play Console → Grow → Play Games Services → Setup → Configuration
PLAY_GAMES_APP_ID=1234567890

# Play Console → Grow → Play Games Services → Setup → Configuration
PLAY_GAMES_APP_ID=1234567890

4. Configure leaderboards and achievements#

Copied!

// config/play-games-services.php
'leaderboards' => [
    'high_score' => env('PLAY_GAMES_LEADERBOARD_HIGH_SCORE'),
],
'achievements' => [
    'first_win' => env('PLAY_GAMES_ACHIEVEMENT_FIRST_WIN'),
],

// config/play-games-services.php
'leaderboards' => [
    'high_score' => env('PLAY_GAMES_LEADERBOARD_HIGH_SCORE'),
],
'achievements' => [
    'first_win' => env('PLAY_GAMES_ACHIEVEMENT_FIRST_WIN'),
],

5. Run native install#

Copied!

php artisan native:install --force

php artisan native:install --force

Configuration#

config/play-games-services.php gives you full control over sign-in behaviour and named slots.

Kill-switch#

Copied!

PLAY_GAMES_ENABLED=false

PLAY_GAMES_ENABLED=false

PlayGamesServices::initialize() silently signs the player back in if they've already granted access — no UI shown. Disable with:

Copied!

PLAY_GAMES_AUTO_SIGN_IN=false

PLAY_GAMES_AUTO_SIGN_IN=false

Named slots#

Reference leaderboards and achievements by name instead of hardcoding raw IDs. Unknown slot names are passed straight through, so raw IDs still work without any config changes.

Usage#

PHP Facade#

Copied!

use NativePHP\PlayGamesServices\Facades\PlayGamesServices;
 
// Call once on app boot — silently signs the player in if already authorized
PlayGamesServices::initialize();
 
// Explicit sign-in (shows the Play Games account picker if needed)
PlayGamesServices::signIn();
 
// Leaderboards
PlayGamesServices::submitScore('high_score', 1500);
PlayGamesServices::showLeaderboard('high_score');
PlayGamesServices::showAllLeaderboards();
 
// Achievements
PlayGamesServices::unlockAchievement('first_win');
PlayGamesServices::incrementAchievement('collect_100_coins', steps: 10);
PlayGamesServices::showAchievements();

use NativePHP\PlayGamesServices\Facades\PlayGamesServices;

// Call once on app boot — silently signs the player in if already authorized
PlayGamesServices::initialize();

// Explicit sign-in (shows the Play Games account picker if needed)
PlayGamesServices::signIn();

// Leaderboards
PlayGamesServices::submitScore('high_score', 1500);
PlayGamesServices::showLeaderboard('high_score');
PlayGamesServices::showAllLeaderboards();

// Achievements
PlayGamesServices::unlockAchievement('first_win');
PlayGamesServices::incrementAchievement('collect_100_coins', steps: 10);
PlayGamesServices::showAchievements();

JavaScript (React, Vue, Alpine, plain JS)#

The JS bridge accepts raw leaderboard/achievement IDs. Slot resolution happens server-side.

Copied!

import {
    initialize, signIn, getCurrentPlayer,
    submitScore, showLeaderboard, showAllLeaderboards,
    unlockAchievement, incrementAchievement, showAchievements,
    onSignedIn, onSignInFailed, onAchievementUnlocked, onPlayGamesEvent,
} from 'vendor/bhargavdetroja/nativephp-play-games-services/resources/js/playGamesServices.js';
 
await initialize();
 
onSignedIn(({ playerId, displayName, avatarUrl }) => {
    console.log(`Signed in as ${displayName}`);
});
 
await submitScore('CgkI...', 1500); // pass the resolved ID from Blade/PHP

import {
    initialize, signIn, getCurrentPlayer,
    submitScore, showLeaderboard, showAllLeaderboards,
    unlockAchievement, incrementAchievement, showAchievements,
    onSignedIn, onSignInFailed, onAchievementUnlocked, onPlayGamesEvent,
} from 'vendor/bhargavdetroja/nativephp-play-games-services/resources/js/playGamesServices.js';

await initialize();

onSignedIn(({ playerId, displayName, avatarUrl }) => {
    console.log(`Signed in as ${displayName}`);
});

await submitScore('CgkI...', 1500); // pass the resolved ID from Blade/PHP

Pass resolved IDs from Blade so slot names work from JS too:

Copied!

<script>
    const HIGH_SCORE_ID = '{{ app("play-games-services")->resolveLeaderboardId("high_score") }}';
</script>

<script>
    const HIGH_SCORE_ID = '{{ app("play-games-services")->resolveLeaderboardId("high_score") }}';
</script>

Listening to Events#

In JavaScript#

Copied!

import { onSignedIn, onAchievementUnlocked, onPlayGamesEvent } from '...';
 
const stop = onSignedIn(({ displayName }) => updateProfileUI(displayName));
 
onAchievementUnlocked(({ achievementId }) => showToast(`Achievement unlocked: ${achievementId}`));
 
onPlayGamesEvent('NativePHP\\PlayGamesServices\\Events\\ScoreSubmissionFailed', ({ leaderboardId, errorMessage }) => {
    console.warn(`Score submission to ${leaderboardId} failed: ${errorMessage}`);
});
 
stop(); // unsubscribe (React/Vue component unmount)

import { onSignedIn, onAchievementUnlocked, onPlayGamesEvent } from '...';

const stop = onSignedIn(({ displayName }) => updateProfileUI(displayName));

onAchievementUnlocked(({ achievementId }) => showToast(`Achievement unlocked: ${achievementId}`));

onPlayGamesEvent('NativePHP\\PlayGamesServices\\Events\\ScoreSubmissionFailed', ({ leaderboardId, errorMessage }) => {
    console.warn(`Score submission to ${leaderboardId} failed: ${errorMessage}`);
});

stop(); // unsubscribe (React/Vue component unmount)

In PHP — standard Laravel events#

Copied!

use NativePHP\PlayGamesServices\Events\SignedIn;
use NativePHP\PlayGamesServices\Events\AchievementUnlocked;
 
public function handle(SignedIn $event): void
{
    auth()->user()->update(['play_games_id' => $event->playerId]);
}

use NativePHP\PlayGamesServices\Events\SignedIn;
use NativePHP\PlayGamesServices\Events\AchievementUnlocked;

public function handle(SignedIn $event): void
{
    auth()->user()->update(['play_games_id' => $event->playerId]);
}

Livewire (v3/v4):

Copied!

use Native\Mobile\Attributes\OnNative;
use NativePHP\PlayGamesServices\Events\SignedIn;
 
#[OnNative(SignedIn::class)]
public function handleSignedIn($playerId, $displayName, $avatarUrl = null)
{
    $this->displayName = $displayName;
}

use Native\Mobile\Attributes\OnNative;
use NativePHP\PlayGamesServices\Events\SignedIn;

#[OnNative(SignedIn::class)]
public function handleSignedIn($playerId, $displayName, $avatarUrl = null)
{
    $this->displayName = $displayName;
}

All Events#

Event	Properties	When it fires
`SignedIn`	`$playerId`, `$displayName`, `$avatarUrl`	Player is authenticated (silent or interactive)
`SignInFailed`	`$errorMessage`	Sign-in was cancelled or failed
`ScoreSubmitted`	`$leaderboardId`, `$score`	Score was accepted by the leaderboard
`ScoreSubmissionFailed`	`$leaderboardId`, `$errorMessage`	Score submission or leaderboard UI failed
`AchievementUnlocked`	`$achievementId`	A standard achievement was unlocked, or an incremental one reached 100%
`AchievementUnlockFailed`	`$achievementId`, `$errorMessage`	Unlock call failed
`AchievementIncremented`	`$achievementId`, `$steps`	An incremental achievement advanced without completing
`AchievementIncrementFailed`	`$achievementId`, `$errorMessage`	Increment call failed

Notes on the Play Games Services v2 SDK#

No programmatic sign-out. Play Games Services v2 ties sign-in to the player's Google Play Games account, not a per-app session — there is no signOut() in the SDK. Users manage this from the Play Games app itself.
incrementAchievement applies a relative delta (steps), matching AchievementsClient.increment(). If the increment causes the achievement to reach 100%, AchievementUnlocked fires instead of AchievementIncremented.
Emulators need a system image with Google Play Services and a Google account signed in in the Play Games app.

Going to Production#

Set your real PLAY_GAMES_APP_ID and leaderboard/achievement IDs in .env.
Publish your app to at least the Internal Testing track — Play Games Services sign-in only works for testers/reviewers on a published (even if internal) build.
Run php artisan native:install --force.
Build your release: php artisan native:run android.

Troubleshooting#

Sign-in silently does nothing Your build isn't signed with the same certificate/App ID registered in Play Console, or the app hasn't been uploaded to any test track yet. Play Games Services requires this even for internal testing.

unknown slot exception You passed a slot name that isn't defined in config/play-games-services.php. Either add it to leaderboards/achievements, or pass a raw ID directly.

Validate plugin setup

Copied!

php artisan native:plugin:validate

php artisan native:plugin:validate

License#

MIT

NativePHP Play Games Services#

Requirements#

Installation#

1. Install the package#

2. Publish the config#

3. Add your Play Games App ID to .env#

4. Configure leaderboards and achievements#

5. Run native install#

Configuration#

Kill-switch#

Auto sign-in#

Named slots#

Usage#

PHP Facade#

JavaScript (React, Vue, Alpine, plain JS)#

Listening to Events#

In JavaScript#

In PHP — standard Laravel events#

All Events#

Notes on the Play Games Services v2 SDK#

Going to Production#

Troubleshooting#

License#

3. Add your Play Games App ID to `.env`#