• Home

FelgoGameNetwork

The root Felgo Game Network component for using leaderboards, achievements and challenges in your game. Note that the Felgo Game Network is currently only available on request. More...

• List of all members, including inherited members

Properties

• achievements : Achievement
• askForWritePermissionsOnlyOnce : bool
• clearAllUserDataAtStartup : bool
• connectionError : alias
• currentActiveLeaderboard : string
• defaultUserName : alias
• displayName : alias
• facebookConnectionState : string
• facebookConnectionSuccessful : bool
• facebookItem : variant
• gameCenterItem : variant
• gameId : alias
• gameNetworkView : variant
• multiplayerItem : variant
• secret : alias
• userAchievementsInitiallySynced : bool
• userCustomData : alias
• userHighscoreForCurrentActiveLeaderboard : int
• userInitiallyInSync : bool
• userName : alias
• userPositionForCurrentActiveLeaderboard : int
• userRanking : alias
• userScoresInitiallySynced : bool

Signals

• achievementUnlockedAfterServerApproval(string)
• challengeAccepted(variant)
• challengeCompleted(variant)
• challengeCreated(variant)
• challengeWithScoreSubmitted(variant)
• facebookConnectionError(variant)
• facebookSuccessfullyConnected()
• facebookSuccessfullyDisconnected()
• newHighscore(string, real)
• newHighscoreAfterServerApproval(string, real, real, int, int)

Methods

• acceptChallenge(challengeId)
• connectFacebookUser()
• createChallenge(toChallengeFriendId)
• deleteUser()
• disconnectFacebookUser(clearLocalData, clearServerDataOfFacebookUser)
• fetchUserDetails(userItem)
• getAchievementFromKey(key)
• getCountryNameFromLocale(locale)
• getDisplayNameFromUserName(userName, userObject)
• getFlagUrlFromLocale(locale)
• incrementAchievement(key, amount, bannerVisible)
• isUserNameSet(userName)
• isValidUserInput(inputString)
• removeFriend(userId, callback)
• reportRelativeScore(score, leaderboard, challengeIdArray, data)
• reportScore(score, leaderboard, challengeIdArray, sortOrder, data, useForFacebook)
• resetUserImage(callback)
• sendFriendRequest(userId, text, callback)
• sendFriendResponse(userId, callback)
• showAchievements()
• showLeaderboard(leaderboard, timeFrame, showImmediately)
• showProfileView()
• sync()
• unlockAchievement(key, bannerVisible)
• updateUserCountryCode(newUserCountryCode)
• updateUserCustomData(newUserData)
• updateUserImage(fileUrl, callback)
• updateUserLocale(newUserLocale)
• updateUserName(newUserName)
• updateUserRanking(newUserRanking)
• uploadImage(fileUrl, callback)
• userHighscoreForLeaderboard(leaderboard, returnHighscoreAsInteger)
• userPositionForLeaderboard(leaderboard)
• userTotalPlayersForLeaderboard(leaderboard)

Detailed Description

The Felgo Game Network is a cross-platform gaming service that allows players around the world to compare game highscores and achievements. Players can also challenge each other across multiple platforms and share their progress on Facebook on all supported platforms by Felgo.

Integration in your game takes less than 10 minutes, so start using it and increase your player retention today!

Note: The Felgo Game Network is currently only available on request. You can contact us to find out more.

Felgo Game Network Benefits

In a nutshell, Felgo Game Network provides these benefits to developers:

• No Extra Accounts or Registrations Required: Players do not need to create an extra account to compare their higshcores or achievements across platforms, which leads to high usage. A login with Facebook is available, but not a requirement for players to use the gaming services. This is a key benefit over other gaming services forcing a registration: in our games we have seen high drop-out rates up to 60% of players who do not use other services because of privacy concerns or feeling unconfident connecting a game with their Facebook account - with Felgo Game Network you can also satisfy these players!
• Full Offline Support: Highscores, achievements and WebStorage can be used even when your players have no Internet connection and get synced automatically as soon as Internet connection is available again.
• Fully customizable UI: Felgo Game Network comes with a ready-made UI so you can integrate it in 10 minutes in your game. However, with the strength of QML you can fully customize all views to your game easily and give it an extra-polished look.
• Export Player Data: You can export your player data and use it for example for sending newsletters to bring your players back to the game, or to promote your other games with personal emails.
• Simple QML API: Use properties and signals to get notified when important things happen, e.g. when the player connected with Facebook, reached a new highscore or unlocked an achievement.
• Sharing to Game Center: With a single API call, you can report your game progress to the Felgo Game Network and also to Apple GameCenter. So your players can use both their familiar game service on iOS and also compare their progress with players on other platforms.
• Easy Facebook Integration: Let your players connect with Facebook in a single QML call. We have integrated posting the player's score and achievements to your player's timeline, so the most important Facebook functionality to bring new downloads and make your players return to your games is already built-in.
• Cloud Storage: With the WebStorage component, storing your data in the cloud is as easy as it can be: you can use it to synchronize your player's data across multiple devices or to change the balancing of your game remotely from our Web Dashboard, without the need to release a new update to the app stores.
• Cross-Platform Leaderboards: In most games players can reach highscores representing how well a player has done in the game. With Felgo Game Network you can use unlimited Leaderboards to let players compare against each other in a competitive way and brag about it on Facebook, keeping them playing. You can either display all scores across all platforms on one leaderboard or filter the leaderboards based on platform, time or users.
• Cross-Platform Achievements: Reward your players with Achievements for reaching certain goals in your game and to give them more incentive to keep playing your game. If connected with Facebook achievements get even synced between different devices of a single player.
• Powerful Challenges: Challenges are a powerful tool to increase player retention as they motivate players to beat a friend's score, especially if you reward them for won challenges for example with in-game credits. Compared to other gaming services, challenges in Felgo Game Network are highly flexible: you can add own challenge game modes, create own leaderboards to let the best challengers compare their scores, or simply provide challenges based on the current highscore the player has.
• Level Sharing: With Felgo Game Network, you can let your players share their user-generated levels easily. This means constant level updates for your players and saves you the time for additional level packs. Even more, you can charge for the levels made by your players and reward your best level creators with the LevelStore, fully customizable to your game. Learn more how you can add user-generated content to your game here.
• Felgo Multiplayer: With Felgo Multiplayer you can easily create real-time or turn-based multiplayer games with features like Matchmaking, ELO Rating, a Friend System, Interactive Chat & Messaging or Push Notifications. Felgo Multiplayer integrates seamlessly with the Felgo Game Network features like leaderboards, achievements or the cloud storage. See the FelgoMultiplayer documentation for more information.

Further Resources

This section is updated with further resources about Felgo Game Network related topics.

• Felgo Game Network Introduction Blog Post - Contains information why Felgo Game Network was created and its highlights
• Felgo Crash Course Lesson 5 - How to increase player retention & downloads in 10 minutes
• Felgo Crash Course Lesson 6 - How to add Facebook & Game Center sharing to your game

The pricing for Felgo Game Network is based on the monthly active users of your game, contact us at support@felgo.com for more information on Felgo Game Network pricing.

How to Add Felgo Game Network to Your Game

This tutorial guides you step-by-step how to add the Felgo Game Network to your game. Adding social features to your game only takes about 10 minutes and increases your player retention, so it is advisable every game makes use of these features.

Web Dashboard

Go to https://cloud.felgo.com and log in with your Felgo user account.

At the Web Dashboard, you can see the following:

• A list of your created games with the generated gameId.
• How many API requests were sent for the game.
• Buttons to create a new game and edit existing ones.

Press the Create a new game button and enter a Game Title and Game Secret for it as shown in the following image. You can leave the Facebook fields empty for now, we will get to it later in section Add Facebook Connection how to use them.

The Game Title you entered is just to distinguish between your games in the dashboard. The secret and the generated gameId you will see in the next view, are the ones you should use for the FelgoGameNetwork component in the next step.

Add the FelgoGameNetwork Component

You can now switch to Qt Creator and add the FelgoGameNetwork component in your main qml file, like in the following example:

 import Felgo 3.0
 import QtQuick 2.0

 GameWindow {

   FelgoGameNetwork {
     // created in the Felgo Web Dashboard
     gameId: 5
     secret: "abcdefg1234567890"
   }

   // add other components like the EntityManager here

   Scene {

     // add your game functionality here

   }
 }

Add the SocialView Default UI

After adding the FelgoGameNetwork component, the next step is to add a view for your game's leaderboards, achievements and player profile. The easiest way to do this, is to add the SocialView component, the default UI that comes with the Felgo SDK.

See the SocialView documentation for more information how to integrate, use and customize the view. For a quick-introduction how to use the most important features, you can have a look at the SocialView Video Tutorial:

See How to Add Chat Service and Cross-Platform Leaderboard with User Profiles to Your iOS or Android App for more information and the full example code.

Add the Deprecated GameNetworkView UI

You also have the option to use the old GameNetworkView UI instead of the SocialView, which e.g. still misses a page for achievements.

However, the SocialView comes with several advantages:

• Felgo Apps Compatibility: The social view is designed for easy usage with Felgo Apps, which usually provide a stack-based layout with the App Navigation components.
• Better Customization Options: It is now possible to extend the view with custom UI elements to e.g. show custom user data without having to directly modify the QML source code of the view.
• Native Look and Feel: The default UI of the new view automatically provides a native style and user experience for iOS and Android.
• Clean Separation of Sub-Pages: The GameNetworkView holds a single instance of each sub-view it provides. This means it is not prepared to show different instances and configurations of e.g. the leaderboard or user profiles within your app. For example, you can only show the profile of one specific user at a given time. The SocialView on the other hand clearly separates the view, custom delegates and available social pages. This also allows to introduce custom pages that can work with the FelgoGameNetwork and FelgoMultiplayer services, without the need to modify the QML source code of the view.

Note: GameNetworkView is deprecated. It will no longer receive updates and fixes, so we recommend to use the SocialView type.

The following sections of this guide still refer to the GameNetworkView. This example shows how to add the deprecated view in your scene to show it in your game:

 import Felgo 3.0
 import QtQuick 2.0

 GameWindow {
   // add other components like the EntityManager here

   FelgoGameNetwork {
     id: gameNetwork
     // created in the Felgo Web Dashboard
     gameId: 5
     secret: "abcdefg1234567890"
     gameNetworkView: myGameNetworkView
   }

   Scene {
     id: scene
     // add your game functionality here

     SimpleButton {
       text: "Show Leaderboards"
       onClicked: {
         // open the leaderboard view of the GameNetworkView
         gameNetwork.showLeaderboard()
       }
     }

     GameNetworkView {
       id: myGameNetworkView
       anchors.fill: scene.gameWindowAnchorItem

       onShowCalled: {
         myGameNetworkView.visible = true
       }

       onBackClicked: {
         myGameNetworkView.visible = false
       }
     }// GameNetworkView

   }// Scene
 }// GameWindow

When you now run this project, you will see the following image:

In the code changes above, the GameNetworkView component was added and set as gameNetworkView property. If the back button is pressed, the normal game scene is shown again with a single button to show the leaderboard. In the GameNetworkView top navigation, you can switch to between the leaderboard, achievement and profile view. The profile view allows the player to change the userName, synchronize the player progress between multiple devices and platforms and to connect with Facebook. More on that topic will follow in the section Add Facebook Connection.

Note: You can also move the GameNetworkView into a different Scene if you want, as it is done in the ChickenOutbreak Demo.

Customize Felgo Game Network UI

The following guide refers to customization of the GameNetworkView. For the SocialView customization options, please see Customize the Features and Look of your Social Services

Note: The GameNetworkView is deprecated and will no longer receive updates and fixes, so we recommend to use the SocialView type.

You can fully customize the Felgo Game Network UI so it looks polished to your game. Have a look at the GameNetworkExample how to write your own GameNetworkView. The following screenshot shows a customized leaderboard used in a game:

Leaderboards

You can use leaderboards in your game to give your players the possibility to compare their higshcores across platforms. This ultimately increases your player retention: your players will return to your game more often and play more and longer.

The minimum usage is to report a new score with reportScore() and then show the score in the LeaderboardView as part of the GameNetworkView with showLeaderboard(). The LeaderboardView is shown in the following image.

These functions and properties are useful for leaderboard usage:

• reportScore() - Report a new highscore to the game.
• reportRelativeScore() - Report a new relative score to the game, useful for incrementing or decrementing a score.
• showLeaderboard() - Opens the GameNetworkView to show the LeaderboardView.
• onNewHighscore - This handler is called after a new highscore was reached, you can handle it to show a notification to the player.
• userScoresInitiallySynced - This property gets set to true after the highscores of the player got synced from the server.
• currentActiveLeaderboard - Holds the currently shown leaderboard name.
• userHighscoreForCurrentActiveLeaderboard - Holds the current highscore of the player for currentActiveLeaderboard.

Note: The friends list contains Facebook friends who also play the same game. See Facebook Friends for Leaderboards and Challenges for more information.

Achievements

Achievements are another way to increase player retention: they motivate players to return to the game, until they have unlocked all achievements in a game. Examples for game achievements are:

• Open a game 5 times.
• Defeat enemy boss of level 2.
• Reach the third level.

You can define these achievements in QML and they get uploaded to the Felgo Game Network server when you run your application on Desktop. This is a key advantage over other gaming services where you are required to leave the code environment and define the achievements in the web - with Felgo Game Network you can fully create and change your achievements in QML code and they are then synced with the server!

For the example achievements given above, this is the code how to define them and to update their progress:

 import Felgo 3.0
 import QtQuick 2.0
 GameWindow {
   Scene {

     FelgoGameNetwork {
       id: gameNetwork
       // created in the Felgo Web Dashboard
       gameId: 5
       secret: "abcdefg1234567890"
       gameNetworkView: myGameNetworkView

       Component.onCompleted: {
         // increment the counter until until the game was opened 5 times
         // after the target value was reached, a call of incrementAchievement() has no more effect
         gameNetwork.incrementAchievement("5opens")

         // in the game logic after defeating the boss of level 2, add the following:
         // gameNetwork.unlockAchievement("bossLevel2")

         // in the game logic after completing a level, call the following:
         // gameNetwork.incrementAchievement("level3")
       }

       achievements: [

         Achievement {
           key: "5opens"
           name: "Game Opener"
           iconSource: "../assets/img/achievement_5opens.png"
           target: 5
           points: 10
           description: "Open this game 5 times"
         },
         Achievement {
           key: "bossLevel2"
           name: "Obsessed Collector"
           iconSource: "../assets/img/achievement_bossLevel2.png"
           target: 1
           points: 5
           description: "Defeat boss enemy of level 2"
         },
         Achievement {
           key: "level3"
           name: "Third Level Master"
           iconSource: "../assets/img/achievement_level3completed.png"
           target: 3
           points: 15
           description: "Reach level 3"
         }
       ]
     }// FelgoGameNetwork

   // other code here

   }// Scene
 }// GameWindow

You can then show the unlocked achievements by calling showAchievements() or clicking the achievement icon in the GameNetworkView. You can modify the progress of the achievements with incrementAchievement() or unlockAchievement() until they are fully unlocked. The following image shows how the AchievementView looks for the ChickenOutbreak Demo:

These functions and properties are useful for achievement usage:

• achievements - Define the Achievement list with the required key, name, target, points and description properties.
• incrementAchievement() - Increase the Achievement::counter property if the achievement is not unlocked yet.
• unlockAchievement() - Unlock the achievement.
• showAchievements() - Opens the GameNetworkView to show the AchievementView.
• onAchievementUnlocked - Use this handler to display a notification or show a dialog when an achievement is unlocked.

Challenges

are a powerful tool to increase player retention as they motivate players to beat a friend's score, especially if you reward them for won challenges for example with in-game credits. If a new challenge is received, you can notify players and make them return to the game.

Compared to other gaming services, challenges in Felgo Game Network are highly flexible: you can add own challenge game modes, create own leaderboards to let the best challengers compare their scores, or simply provide challenges based on the current highscore the player has.

The implementation flow for challenges looks like this:

1. PlayerA chooses a friend for the challenge and receives a lastCreatedChallengeData and onChallengeCreated.
2. PlayerA reports a score to the challenge by providing the previously created challengeId to reportScore().
3. PlayerB updates the open challenge list and accepts the challenge with acceptChallenge().
4. PlayerB reports a score to the accepted challenge by providing the previously created challengeId to reportScore().
5. The result of the challenge with information who is the winner is received in onChallengeCompleted.

The challenges are not available as default UIs with GameNetworkView yet. Please contact our support team for help in customizing your own ChallengeView and see the GameNetworkExample for a reference implementation of challenges.

Note: Challenges can only be performed between Facebook friends. See Facebook Friends for Leaderboards and Challenges for more details.

WebStorage for Cloud Data

The WebStorage component is part of the Felgo Game Network and can be used to

• Synchronize your player's data across multiple devices (and across platforms!). This means your player can start playing on an iPhone, later at home continue playing on a desktop PC and maybe then continue on his Android tablet, with unified game data that gets synced automatically.
• Change the balancing of your game remotely from a web dashboard. The remote values get updated the next time the user starts the application. This has the benefit you can control any property values when your game is already launched, without releasing an update for your app. This means you also save the time to wait for the update approval, which can last up to three weeks for Apple.

For more details how to use this component, see the WebStorage documentation.

Add Facebook Connection

One of the biggest benefits of Felgo Game Network is the built-in Facebook connection. Although your players can also achieve highscores and achievements without connecting to their Facebook account, they get the following benefits after connecting with Facebook:

• Players can compare their highscores with their friends in the Friends section of daily, weekly and all time leaderboards. Thus players know which ranking they have within their friends also playing your game, and not only in the overall leaderboard list.
• Highscores and achievements are automatically posted to your players timeline. This increases player retention, i.e. your players return more often to your game thanks to the open graph stories that are created. Also, this will bring you new downloads for your game, because the stories are also visible to all your player's friends not playing your game, yet!
• Challenges only work between Facebook friends.
• Syncing the player's data across devices and platform is only possible if the player connects with the same Facebook account from multiple devices. After the initial connect from multiple devices, the player can sync all Felgo Game Network data: highscores, achievements, challenges and WebStorage data.

In your game, it is advisable to communicate these benefits to your players. You can do so by checking the facebookConnectionSuccessful property at app startup, and ask the player to connect to gain these benefits. In the ProfileView, a part of the default GameNetworkView, we also have communicated the benefits as you can see in the following picture. Based on the facebookConnectionSuccessful status, a different text is displayed. In the image the player did already connect with Facebook, thus he is shown information what he gains from this connection and when he should use the disconnect functionality.

Facebook Stories that Are Posted to the Players Timeline

If the player connects with Facebook, the highscore progress and unlocked achievements are automatically posted to the timeline. These graph stories are visible to all of your player's friends and thus will bring you new downloads: If the player clicks the story in the mobile Facebook app, this will directly open your game!

As Felgo Game Network internally uses the Score API (where the following image is taken from), this story is posted automatically on your player's timeline if he reaches a better highscore:

If an achievement is unlocked, this is also posted in the player's timeline. The following image shows common stories that are visible in the player's Activity Log:

If one of these graph stories is clicked on a mobile device, your app is started from the Facebook native application. If it is clicked in a web browser, the canvas page is shown which serves as an advertisement page for your game. More details on the canvas page are available in section Facebook App Settings.

Facebook Friends for Leaderboards and Challenges

In the Friends top section of the LeaderboardView the Facebook friends of the player are listed. Only the friends who also connected their device with your Facebook app, and already reported a score are listed there. Similarly, players can only challenge players who are their Facebook friends and did also connect with your Facebook app.

Step-By-Step Tutorial How to Add Facebook to Your Mobile Game or App

The following sections describe the steps required for adding Facebook connection to your game. This also applies to apps that use Felgo Game Network and Facebook for social or gamification elements.

Here is a quick overview of the steps needed:

1. Setup your Facebook App Settings
2. Add Facebook Components to Your Game/App
3. Submit your Facebook App for Review
4. Add Facebook to the Web Dashboard

Facebook App Settings

Go to http://developers.facebook.com/apps and create a new Facebook app. On the dashboard, add Facebook Login by clicking "Set Up". You can skip the quickstart guide, as the FelgoGameNetwork already handles these steps.

In the app settings you now see your App ID and App Secret, which you will need in the next step. It is important to choose Game as category, otherwise you will not be able to post highscores and achievements.

To post achievements on your player's behalf it is required to add vplay-network.herokuapp.com to the App Domains. You should also create a Facebook canvas page, which is shown when users click on the Facebook graph stories in their web browser. If this html page is for example hosted on https://felgo.com/facebook/chickenoutbreak/index.html, add felgo.com to the App Domains. The following screenshot shows the settings of a test application, where we set the canvas url to the one of ChickenOutbreak Demo.

For quick testing, you can also skip the step of adding a custom Facebook canvas page and use the one generated by Felgo Game Network when you created a new game in the Web Dashboard. However, this page is an empty white page only showing the name of your game, so make sure to add a Facebook page to promote your game when you publish it. The url for adding the Felgo page is http://v-play.herokuapp.com/canvas/<your-VPlay-GameId>/ - with <your-VPlay-GameId> being the gameId.

To test your game on iOS & Android, add these platforms in the Facebook settings. Enter your game identifier you have set in the config.json file as the iOS Bundle ID and Android Package Name. The Class Name should be set to net.vplay.helper.VPlayActivity, which is also set in your android/AndroidManifest.xml configuration. For Android, also add the Key Hashes for each of your used signing certificates. See Facebook::printAndroidKeyHash() on how to get your key hashes. The following screenshot shows example settings to configure your Facebook app for iOS & Android.

Note: The Deep Linking setting will launch your game when users click on a message in their timeline. We recommend to enable it, as it brings players back to your game.

Adding the Facebook Component to Your Game

After creating the Facebook app, add the Facebook component to your main qml file. The following example shows the Facebook additions: add the import Felgo 3.0 statement, the Facebook component with your Facebook::appId and set the facebookItem property to the id of your Facebook item.

 import Felgo 3.0
 import QtQuick 2.0

 GameWindow {

   Facebook {
     // the user will automatically connect with facebook
     // once "connect" is pressed in the ProfileView in the GameNetworkView
     id: facebook

     // this is the Facebook App Id received from the settings in developers.facebook.com/apps
     appId: "569422866476284"

     readPermissions: [ "public_profile", "email", "user_friends" ]
     publishPermissions: [ "publish_actions" ]
   }

   FelgoGameNetwork {
     id: gameNetwork
     // created in the Felgo Web Dashboard
     gameId: 5
     secret: "abcdefg1234567890"
     gameNetworkView: myGameNetworkView

     facebookItem: facebook
   }

   // the Scene will follow here

 }// GameWindow

Note: The user_friends permission only allows to get a list of friends that also use your app and are connected to Facebook.

Submitting your Facebook App for Review

Facebook requires you to submit your app for review. They need to approve each type of user data item your app wants to access. These items are, for example, the user's friends, posts, or liked pages. In the developer dashboard, click "App Review".

Then click "Start a Submission". Here you can add the privacy concerning permissions your app or game uses.

To allow users seeing their friends' highscores first, you need the friends list permission. For this, check the user_friends item from the list.

Facebook requires a description of how your app or game uses the friends list. Click "details" and describe how to use Facebook login and friends list step by step. You can use this template, adapted to how to reach Facebook login in your app or game:

 The game uses the player's friends to show their highscores first:
 1. Click Highscores in main menu
 2. Click "Connect with Facebook"
 3. Facebook Login opens
 4. Login with facebook
 5. Click Highscores button on top right (123 icon)
 6. Highscores show your friends who have played the game before on top

You will also need to upload a video how the Facebook login works in your app or game. You can use a screen recording tool to create a video similar to this:

Then you can submit your app for review. It usually takes between 24 hours to 14 days until your app gets approved. Once the app was approved, you can use Facebook integration with FelgoGameNetwork.

Adding Facebook to the Web Dashboard

As the final step, add the Facebook settings to the Web Dashboard at https://cloud.felgo.com, choose Edit for your game and add the Facebook specific information like shown in this image:

The Facebook App ID is the Facebook::appId, the Facebook Secret the one you received from the Facebook App Settings, and the Facebook Canvas Url is http://vplay-network.herokuapp.com/canvas/<your-VPlay-GameId>. As the gameId in this example was 5, the canvas url for this game is http://vplay-network.herokuapp.com/canvas/5. It is important that you do not add a trailing slash ("/") at the end of the Facebook Canvas Url. Also, setting the Facebook Canvas Url is only required if you want to allow your players to share their achievements on Facebook, which is recommended because it increases player retention.

After these steps, you can test the Facebook connection by going to the ProfileView in the GameNetworkView and choose the "Connect with Facebook" button. For more details how to test the Facebook connection, see Test the Facebook Connection.

Add Game Center Connection

Felgo Game Network allows you to use GameCenter on iOS together with the Felgo Game Network. So players can both compare their highscores on iOS with their GameCenter account, and also across platforms with the Felgo Game Network.

The highscore and achievements are posted to both game services with a call of reportScore(), incrementAchievement() and unlockAchievement(), if you set the gameCenterItem property to your GameCenter id.

The following example shows how GameCenter support is added to Felgo Game Network:

 import Felgo 3.0
 import QtQuick 2.0

 GameWindow {

   // make sure to enable GameCenter for your application (developer.apple.com)
   GameCenter {
     id: gameCenter
   }

   FelgoGameNetwork {
     id: gameNetwork
     // created in the Felgo Web Dashboard
     gameId: 5
     secret: "abcdefg1234567890"
     gameNetworkView: myGameNetworkView
     facebookItem: facebook

     // by setting the gameCenterItem property, scores and achievements are also posted to GameCenter
     gameCenterItem: gameCenter
   }

   // the Scene will follow here

 }// GameWindow

See the GameCenter documentation how to set up the achievements and leaderboards from iTunes Connect.

Test and Release Your Game

You can test the whole Felgo Game Network functionality on all supported platforms of Felgo: on the Desktop platforms Windows, Mac and Linux and the mobile platforms iOS, Android, BlackBerry, Symbian and MeeGo.

Currently you cannot clear your leaderboards or unlocked achievements in the Web Dashboard. If you would like to do so, please contact us in our support forums.

We recommend to create a second game for the live version of your game in the Web Dashboard, because you then don't mix your developer data with the live data and you start the live version with clean leaderboards and achievements. To do so, just rename your game in the dashboard to another name (in the image we appended a "Dev" at the end of the Chicken Outbreak game that is live in the app stores, to indicate the gameId 1 is the dev version). Afterwards create a new game with a new gameId and secret, which you only use when you are publishing your game. It is also advisable to create a new Facebook app to avoid mixing your developer data with the live Facebook app.

Limitations for Testing on Desktop

You can test highscores, achievements and challenges on Desktop as well as on your mobile devices. The only functionality not working on Desktop is the Facebook connection, as there is no Facebook plugin available on Desktops yet. So the friends section of your leaderboards will always be empty on Desktop platforms, and you cannot create new Challenges as there is no friend list available.

Test the Facebook Connection

Testing Facebook connection is most convenient with the GameNetworkView and the ProfileView. You can enter the ProfileView by pressing the "More" button in the LeaderboardView or AchievementView and choose Profile. The following image shows the "More Menu" of the LeaderboardView.

Based on the facebookConnectionState property, a different text is displayed. In the image below the player did already connect with Facebook, thus he is shown information what he gains from this connection and when he should use the disconnect functionality.

Note: Testing the Facebook connection is only possible on iOS and Android devices.

If you connect with Facebook for the first time, you are asked to allow three permissions for your app in this order:

1. Accept overall access to your Facebook app.
2. Accept the Facebook::readPermissions to access the friend list.
3. Accept the Facebook::publishPermissions to allow posting on the player's timeline about achievement and highscore progress.

Each permission is explained to your players with a native dialog to grant the permission to your app. The following image is taken from the Facebook doc and shows how these dialogs look on iOS and Android.

If your app is set as Sandbox mode in the Facebook App Settings, make sure the Facebook user you are connecting with has access to the Facebook app. See the Roles tab in the Facebook App Settings which Facebook users have access to your app.

After connecting the player with Facebook, any further call of reportScore(), incrementAchievement() or unlockAchievement() will post a graph story to the connected user's timeline. Facebook handles it internally when the story is visible in the timeline, but in the Activity Log you will see all stories that have been posted as shown in the following image.

To test the Facebook connection with a different user, follow the instructions in the Facebook item how to Logout from Facebook Account. If you also want to test the permission dialogs again, go to https://www.facebook.com/appcenter/my to view Your Apps and remove the app from your Facebook account with the Settings button. The following image shows how the Facebook Your Apps page looks.

Test Cross-Platform Syncing

If you now connect with the same Facebook user from another device (regardless of the platform), all the highscore, achievement, challenge and WebStorage data is synchronized automatically at this initial connection. It is also synced every time your game is started if it was closed before (make sure to really close it and not just move it to background). For an explicit sync, you can use the Sync button in the ProfileView or call sync() in your game logic.

Example Usage

This example shows how to add the FelgoGameNetwork to a game. It contains Facebook connection to sync your game progress across platforms and to share achievements and highscore updates on Facebook.

The game logic is simulated with buttons to show the GameNetworkView, increase the current player highscore and unlock achievements. You can run this example on the Desktop and all supported mobile platforms of Felgo including iOS, Android, Symbian and MeeGo.

 import Felgo 3.0
 import QtQuick 2.0

 GameWindow {

   Facebook {
     // the user will automatically connect with facebook
     // once "connect" is pressed in the ProfileView in the GameNetworkView
     id: facebook

     // this is the Facebook App Id received from the settings in developers.facebook.com/apps
     appId: "569422866476284"

     readPermissions: [ "public_profile", "email", "user_friends" ]
     publishPermissions: [ "publish_actions" ]
   }// Facebook

   FelgoGameNetwork {
     id: gameNetwork
     // created in the Felgo Web Dashboard
     gameId: 5
     secret: "abcdefg1234567890"
     gameNetworkView: myGameNetworkView
     facebookItem: facebook

     Component.onCompleted: {
       // increment the counter until until the game was opened 5 times
       // after the target value was reached, a call of incrementAchievement() has no more effect
       gameNetwork.incrementAchievement("5opens")
     }

     achievements: [

       Achievement {
         key: "5opens"
         name: "Game Opener"
         // comment this until you have your own images for achievements
         //iconSource: "../assets/img/achievement_5opens.png"
         target: 5
         points: 10
         description: "Open this game 5 times"
       },
       Achievement {
         key: "bossLevel2"
         name: "Obsessed Collector"
         //iconSource: "../assets/img/achievement_bossLevel2.png"
         target: 1
         points: 5
         description: "Defeat boss enemy of level 2"
       },
       Achievement {
         key: "level3"
         name: "Third Level Master"
         //iconSource: "../assets/img/achievement_level3completed.png"
         target: 3
         points: 15
         description: "Reach level 3"
       }
     ]
   }// FelgoGameNetwork

   Scene {
     id: scene

     // add your game functionality here
     // for this simple example we simulate the game logic with buttons
     // place the buttons below each other in a Column with little spacing in between
     Column {
       spacing: 3

       SimpleButton {
         text: "Show Leaderboards"
         onClicked: {
           // open the leaderboard view of the GameNetworkView
           gameNetwork.showLeaderboard()
         }
       }
       SimpleButton {
         text: "Increase Highscore to " + (gameNetwork.userHighscoreForCurrentActiveLeaderboard + 1)
         onClicked: {
           // increase the current highscore by 1
           gameNetwork.reportScore(gameNetwork.userHighscoreForCurrentActiveLeaderboard + 1)
         }
       }
       SimpleButton {
         text: "Unlock bossLevel2 Achievement"
         onClicked: {
           // unlocks the achievement
           gameNetwork.unlockAchievement("bossLevel2")
         }
       }
       SimpleButton {
         text: "Increase Level3 Achievement"
         onClicked: {
           // increase until it is unlocked, then this function does nothing
           gameNetwork.increaseAchievement("level3")
         }
       }
     }// Column

     // the GameNetworkView will be shown on top of the buttons initially
     GameNetworkView {
       id: myGameNetworkView
       // use the whole GameWindow without borders on different aspect ratios
       anchors.fill: scene.gameWindowAnchorItem

       onShowCalled: {
         myGameNetworkView.visible = true
       }

       onBackClicked: {
         myGameNetworkView.visible = false
       }
     }// GameNetworkView

   }// Scene
 }// GameWindow

You can see Felgo Game Network and GameNetworkView live in the app store game Chicken Outbreak. The full source code is available as part of the Felgo SDK.

For a full example testing the whole Felgo Game Network functionality, also see the GameNetworkExample and GameNetworkSimpleExample.

Felgo Game Network & GDPR

Felgo Game Network provides APIs to comply with the terms of GDPR as set forth by the European Union, including reading, updating and deleting user data for a specific Felgo Game Network user account.

If using Felgo Game Network as a publisher of an app or game, it is up to you to make sure that you provide those APIs to your users. As an example, if you write any (personal) information to the WebStorage, you should add an option to delete all stored data for a given user account.

In the terms of GDPR, Felgo is a data processor on behalf of a Developer using the Felgo Game Network. We optionally provide a Data Processing Agreement, which can be requested by using the provided contact form.

Whether you are using Felgo Game Network or not, it is a good idea to include a Privacy Policy in your app or game and state if and which personal information you are processing within the app. For apps or games including Felgo Game Network you can additionally link to our Privacy Notes for Felgo Apps and Games.

Reading & Updating Data

When using GameNetworkView or SocialView, data is shown and can be changed on the profile view. When not included, you can use the APIs listed at FelgoGameNetwork.

Deleting Data

If you are using GameNetworkView or SocialView, Felgo already includes an option to delete a user's account from within the profile view. If you don't use default views, you can still provide such an action by calling the provided FelgoGameNetwork::deleteUser() API.

Property Documentation

 achievements: [

    Achievement {
      key: "5opens"
      name: "Game Opener"
      iconSource: "../assets/img/achievement_5opens.png"
      target: 5
      points: 10
      description: "Open this game 5 times"
    },
    Achievement {
      key: "bossLevel2"
      name: "Obsessed Collector"
      iconSource: "../assets/img/achievement_bossLevel2.png"
      target: 1
      points: 5
      description: "Defeat boss enemy of level 2"
    },
    Achievement {
      key: "level3"
      name: "Third Level Master"
      iconSource: "../assets/img/achievement_level3completed.png"
      target: 3
      points: 15
      description: "Reach level 3"
    }
  ]

 FelgoGameNetwork {

   // other GameNetwork here ...

   onConnectionErrorChanged: {
     console.debug("GameNetworkTestMain: connectionError changed to", connectionError)
     if(!connectionError) {
       nativeUtils.displayMessageBox("Active Connection", "You just got access to the Internet after previously being disconnected. Your local progress gets now synced with the server.")
     } else {
       nativeUtils.displayMessageBox("Lost Internet Connection", "You just got disconnected from the Internet. Your local progress will be stored for later until you get Internet access again.")
     }
   }
 }

 FelgoGameNetwork {
   id: gameNetwork
 }

 Text {
   text: "Your highscore: " + gameNetwork.userHighscoreForCurrentActiveLeaderboard
 }

 FelgoGameNetwork {
   id: gameNetwork
 }

 Text {
   text: "Your ranking: " + gameNetwork.userPositionForCurrentActiveLeaderboard
 }

Signal Documentation

Method Documentation

 gamenetwork.removeFriend(userId, function(success) {
   console.debug("Friend removed, success:", success)
 })

 FelgoGameNetwork {
   id: gameNetwork
 }

 Text {
   text: "current highscore: " gameNetwork.userHighscoreForCurrentActiveLeaderboard
 }

 function gameLogic() {

   // reports the value 14 to the leaderboard "defaultLeaderboard"
   gameNetwork.reportScore(14)
 }

 gamenetwork.resetUserImage(fileUrl, function(success) {
   console.debug("Reset profile image, success:", success)
 })

 gamenetwork.sendFriendRequest(userId, "Please add me as friend", function(success) {
   console.debug("Friend request sent, success:", success)
 })

 gamenetwork.sendFriendResponse(userId, function(success) {
   console.debug("Friend response sent, success:", success)
 })

 gamenetwork.updateUserImage(fileUrl, function(success) {
   console.debug("Updated profile image, success:", success)
 })

 gamenetwork.uploadImage(fileUrl, function(success, url) {
   console.debug("File upload succeeded:", success, "URL:", url)
 })

 import QtQuick 2.5

 Image {
   autoTransform: true
 }

 import Felgo 3.0
 import QtQuick 2.5

 GameWindow {

   property bool shownEditPhotoDialog: false
   property bool shownImagePickerDialog: false
   property bool shownCameraDialog: false

   Scene {
     Column {
       spacing: 5

       GameButton {
         text: "Edit Image"
         onClicked: {
           // no camera feature on desktop, so just show file dialog
           if (system.desktopPlatform) {
             displayImagePicker()
           }
           else {
             shownEditPhotoDialog = true
             nativeUtils.displayAlertSheet("", ["Choose Photo", "Take Photo", "Reset Photo"], true)
           }
         }
       }

       Image {
         id: userImage

         autoTransform: true
         fillMode: Image.PreserveAspectFit

         width: 100
         height: 100
       }

     }
   }// Scene

   FelgoGameNetwork {
     id: gameNetwork
     // created in the Felgo Web Dashboard, create your own at https://cloud.felgo.com/
     gameId: 5
     secret: "abcdefg1234567890"
   }


   Connections {
     target: nativeUtils

     onAlertSheetFinished: {
       if (shownEditPhotoDialog) {
         console.debug("Selected option:", index)
         // Choose
         if (index == 0) {
           displayImagePicker()
         }
         // Take from camera
         else if (index == 1) {
           displayCameraPicker()
         }
         // Reset image
         else if (index == 2) {
           userImage.source = ""
         }

         shownEditPhotoDialog = false
       }
     }

     onImagePickerFinished: {
       if (shownImagePickerDialog) {
         console.debug("Image picker finished with path:", path)
         if (accepted) {
           gameNetwork.uploadImage(path, function(success, url) {
             console.debug("File upload succeeded:", success, "URL:", url)
             // we could do something with the url parameter here, e.g. store it in a WebStorage component
           })
           userImage.source = path
         }
         shownImagePickerDialog = false
       }
     }

     onCameraPickerFinished: {
       if (shownCameraDialog) {
         console.debug("Camera picker finished with path:", path)

         if (accepted) {
           gameNetwork.uploadImage(path, function(success, url) {
             console.debug("File upload succeeded:", success, "URL:", url)
             // we could do something with the url parameter here, e.g. store it in a WebStorage component
           })
           userImage.source = path
         }
         shownCameraDialog = false
       }
     }
   }

   function displayImagePicker() {
     shownImagePickerDialog = true
     nativeUtils.displayImagePicker(qsTr("Profile Image"))
   }

   function displayCameraPicker() {
     shownCameraDialog = true
     nativeUtils.displayCameraPicker()
   }

 }