https://github.com/edimuj/cordova-plugin-gpgs
Modern Cordova plugin for Google Play Games Services v2 API with comprehensive gaming features.
https://github.com/edimuj/cordova-plugin-gpgs
Last synced: 11 months ago
JSON representation
Modern Cordova plugin for Google Play Games Services v2 API with comprehensive gaming features.
- Host: GitHub
- URL: https://github.com/edimuj/cordova-plugin-gpgs
- Owner: edimuj
- License: other
- Created: 2025-06-05T07:29:45.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-06-13T11:33:46.000Z (about 1 year ago)
- Last Synced: 2025-07-12T12:46:02.198Z (11 months ago)
- Language: Java
- Size: 85.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Google Play Games Services Plugin for Cordova
A modern Cordova plugin for Google Play Games Services v2 API with comprehensive gaming features.
## Features
- **Authentication**
- Manual silent sign-in via initialize()
- Background sign-out detection
- Manual sign-in support
- Sign-in state events
- Modern v2 authentication flow
- **Leaderboards**
- Submit scores
- Show leaderboards
- Get player scores
- Get player rankings
- **Achievements**
- Unlock achievements
- Increment achievements
- Show achievements UI
- Reveal hidden achievements
- Set achievement steps
- Load all achievements
- **Cloud Saves**
- Save game data
- Load game data
- Show saved games UI
- Conflict resolution
- Snapshot management
- Delete a snapshot
- Load all snapshots
- **Friends**
- Get friends list
- Show player profiles
- Player search
- Compare profiles
- **Player Stats**
- Get player info
- Get player stats
- Get player level info
- **Events**
- Increment events
- Get event data
- Get all events
- Event tracking
## Requirements
- Cordova >= 12.0.0
- Cordova Android >= 14.0.0
- Android SDK >= 24
- Google Play Services >= 21.2.0
## Installation
```bash
cordova plugin add cordova-plugin-gpgs --variable APP_ID="your-app-id" --variable PLAY_SERVICES_VERSION="23.2.0"
```
### Configuration Variables
- `APP_ID` (required): Your Google Play Games App ID
- `PLAY_SERVICES_VERSION` (optional): Version of Google Play Services to use (default: 23.2.0)
## Configuration
Add the following to your `config.xml`:
```xml
```
## Usage
### Initialization
Call `initialize()` once after `deviceready`. It performs a silent sign-in and fires the usual events (`gpgs.signin`, `gpgs.signout`, `gpgs.availability`). All Play Games API calls that require authentication should be made after the `gpgs.signin` event has fired.
```javascript
document.addEventListener('deviceready', () => {
GPGS.initialize()
.then(() => {
console.log('GPGS initialization request sent');
})
.catch(console.error);
});
```
The plugin NO LONGER attempts silent sign-in automatically; you are in full control of when the operation happens.
### Authentication
```javascript
// Check if Google Play Services are available
GPGS.isGooglePlayServicesAvailable().then(result => {
if (result === true) {
console.log('Google Play Services are available');
} else if (typeof result === 'object') {
console.log('Google Play Services are not available:', result.errorString);
if (result.isUserResolvable) {
// Show UI to help user resolve the issue
}
}
});
// Returns: Promise - If services are not available, returns an object with:
// {
// available: false,
// errorCode: number,
// errorString: string,
// isUserResolvable: boolean
// }
// Check if user is signed in
GPGS.isSignedIn().then(result => {
if (typeof result === 'object') {
console.log('Sign-in status:', result.isSignedIn);
} else {
console.log('Sign-in status:', result);
}
});
// Returns: Promise - Returns either a boolean or an object with:
// {
// isSignedIn: boolean
// }
// Manual sign-in
GPGS.login().then(() => {
console.log('Sign-in successful');
}).catch(error => {
console.error('Sign-in failed:', error);
});
// Returns: Promise
```
### Leaderboards
```javascript
// Submit a score
GPGS.submitScore('leaderboard_id', 1000).then(() => {
console.log('Score submitted');
});
// Returns: Promise
// Show a leaderboard
GPGS.showLeaderboard('leaderboard_id').then(() => {
console.log('Leaderboard shown');
});
// Returns: Promise
// Show all leaderboards
GPGS.showAllLeaderboards().then(() => {
console.log('All leaderboards shown');
});
// Returns: Promise
// Get player's score
GPGS.getPlayerScore('leaderboard_id').then(score => {
console.log('Player score:', score);
});
// Returns: Promise<{
// player_score: number,
// player_rank: number
// }>
// --- Parameter enums ------------------------------------------------------
// timeSpan → 0 = daily, 1 = weekly, 2 = all-time
// collection → 0 = public, 1 = friends
// For richer code samples see: examples/scores.md
// Load top scores for a leaderboard
GPGS.loadTopScores('leaderboard_id', 2 /*all-time*/, 0 /*public*/, 25).then(result => {
console.log('Leaderboard:', result.leaderboard);
console.log('Scores:', result.scores);
});
// Returns: Promise
// -------------------------------------------------------------------------
// See examples/scores.md for showing a leaderboard slice around the player
// Load scores centered around the signed-in player
GPGS.loadPlayerCenteredScores('leaderboard_id', 2 /*all-time*/, 0 /*public*/, 25).then(result => {
console.log('Leaderboard:', result.leaderboard);
console.log('Scores:', result.scores);
});
// Returns: Promise
// Load metadata for a single leaderboard
GPGS.loadLeaderboardMetadata('leaderboard_id').then(metadata => {
console.log('Leaderboard Metadata:', metadata);
});
// Returns: Promise
// Load metadata for all leaderboards
GPGS.loadLeaderboardMetadata().then(metadata => {
console.log('All Leaderboards Metadata:', metadata);
});
// Returns: Promise>
```
### Achievements
```javascript
// Unlock an achievement
GPGS.unlockAchievement('achievement_id').then(() => {
console.log('Achievement unlocked');
});
// Returns: Promise
// Increment an achievement
GPGS.incrementAchievement('achievement_id', 1).then(() => {
console.log('Achievement incremented');
});
// Returns: Promise
// Show achievements UI
GPGS.showAchievements().then(() => {
console.log('Achievements UI shown');
});
// Returns: Promise
// Reveal a hidden achievement
GPGS.revealAchievement('achievement_id').then(() => {
console.log('Achievement revealed');
});
// Returns: Promise
// Set achievement steps
GPGS.setStepsInAchievement('achievement_id', 5).then(() => {
console.log('Achievement steps set');
});
// Returns: Promise
// Load all achievements
GPGS.loadAchievements(false).then(achievements => {
console.log('Achievements:', achievements);
});
// Returns: Promise>
// Get friends list
GPGS.getFriendsList().then(friends => {
console.log('Friends:', friends);
});
// Returns: Promise>
// Show player profile
GPGS.showPlayerProfile('player_id').then(() => {
console.log('Player profile shown');
});
// Returns: Promise
// Show player search
GPGS.showPlayerSearch().then(() => {
console.log('Player search shown');
});
// Returns: Promise
```
### Cloud Saves
```javascript
// Save game data
GPGS.saveGame('save_name', 'description', {
level: 1,
score: 1000
}).then(() => {
console.log('Game saved');
});
// Returns: Promise
// Load game data
GPGS.loadGame('save_name').then(data => {
console.log('Game loaded:', data);
});
// Returns: Promise - The saved game data
// Show saved games UI
GPGS.showSavedGames({
title: 'Saved Games',
allowAddButton: true,
allowDelete: true,
maxSnapshots: 5
}).then(() => {
console.log('Saved games UI shown');
});
// Returns: Promise
// Delete a snapshot
GPGS.deleteSnapshot('save_name').then(snapshotId => {
console.log('Snapshot deleted:', snapshotId);
});
// Returns: Promise
// Load all snapshots
GPGS.loadAllSnapshots(false).then(snapshots => {
console.log('All snapshots:', snapshots);
});
// Returns: Promise>
```
### Player Stats
```javascript
// Get player info
GPGS.getPlayerInfo('player_id', true).then(info => {
console.log('Player info:', info);
});
// Returns: Promise<{
// id: string,
// displayName: string,
// title: string,
// levelInfo?: {
// currentLevel: number,
// maxXp: number,
// minXp: number
// }
// }>
// Get player stats
GPGS.getPlayerStats().then(stats => {
console.log('Player stats:', stats);
});
// Returns: Promise<{
// averageSessionLength: number,
// daysSinceLastPlayed: number,
// numberOfPurchases: number,
// numberOfSessions: number,
// sessionPercentile: number,
// spendPercentile: number,
// spendProbability: number
// }>
```
### Events
```javascript
// Increment an event
GPGS.incrementEvent('event_id', 1).then(() => {
console.log('Event incremented');
});
// Returns: Promise
// Get all events
GPGS.getAllEvents().then(events => {
console.log('All events:', events);
});
// Returns: Promise>
// Get specific event
GPGS.getEvent('event_id').then(event => {
console.log('Event:', event);
});
// Returns: Promise<{
// id: string,
// name: string,
// description: string,
// value: number
// }>
```
## Events
The plugin emits the following events:
### `gpgs.signin`
Emitted when sign-in state changes.
```javascript
{
isSignedIn: boolean,
error?: string // Present if sign-in failed
}
```
### `gpgs.signout`
Emitted when user signs out (including background sign-out).
```javascript
{
isSignedIn: false,
reason: string // e.g., "background_signout"
}
```
### `gpgs.availability`
Emitted when Google Play Services availability changes.
```javascript
{
available: boolean,
errorCode?: number,
errorString?: string,
isUserResolvable?: boolean
}
```
## Error Handling
The plugin uses promises for all operations. Errors are passed to the catch handler:
```javascript
GPGS.login().catch(error => {
console.error('Error:', error.message, 'Status Code:', error.statusCode);
});
```
The error object contains:
- `message`: A descriptive error message
- `statusCode`: The status code from the underlying Google Play Games SDK (if available)
Common error codes from the SDK can be found in the official documentation.
## Debug Mode
Enable debug mode in `config.xml` to see detailed logs:
```xml
```
## License
This project is licensed under the GPL-3.0-or-later License - see the [LICENSE](LICENSE) file for details.
## Author
Exelerus AB - [https://exelerus.com](https://exelerus.com)
## Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## Examples
- [Listening to sign-in events](examples/events.md)
- [Working with leaderboards & scores](examples/scores.md)