Integrating with Your Mobile App Without Using SDK

In this guide, we'll explore how to integrate Gameball within your mobile app without using Gameball’s SDK. This can be helpful if your mobile app framework does not have an out of the box SDK provided by Gameball like Flutter or ionic. Or you choose not to use the SDK for any reason. So let's get started!
Before we dive deeper into integrating Gameball into your mobile app without using an SDK, let's first take a look at the common integration touch points that you'll encounter. These touch points are the areas in your app where you'll need to make changes to incorporate Gameball's features seamlessly. The following touch points will be covered
This guide is not framework specific. Below is a general high level guideline illustrating how to integrate Gameball with applicable mobile frameworks

Gameball user profile sync

The first touch point is the login/registration screen. This is where users create an account or sign in to an existing account in your app. Gameball requires users' profiles to be synced to track their progress and reward them accordingly.
User profiles can be synced using the Create Player API method. Where it creates or updates the player’s profile with each call.
It's recommended that the Create Player API is called with every login or account update.
Depending on your app design, profile sync API calls can be made from your backend system or from within the app.

Show Gameball user profile

The second touch point is to show the player's loyalty profile from Gameball within your app. This is where users can view their progress, points, and rewards.
There are two ways to integrate Gameball's loyalty profile into your mobile app:
  1. 1.
    Using the out-of-the-box widget
Gameball offers pre-built widget that you can easily add to your mobile app if your framework supports Webviews.
let's illustrate the sequence to show Gameball profile widget using Webview:
  1. 1.
    Add menu item to your app menu or player's profile page
  2. 2.
    Upon click, open Webview that points to a self-hosted webpage with Gameball widget scripts embedded in it.
  3. 3.
    Pass player's data to Webview
The first step is to create a blank HTML page and host it at your desirable domain path as below
https://yourdomain.com/webview-address/index.html
This created empty page will be responsible to load Gameball widget for your mobile app user.
On page header include Gameball widget loading script as described in Install Gameball Profile section
<script>
window.GbLoadInit = function(){
GbSdk.init({
playerUniqueId: '{{playerUniqueId}}',
lang: 'en',
playerAttributes:{},
APIKey: '{{Your_API_Key}}'
});
};
</script>
<script defer src="https://assets.gameball.co/widget/js/gameball-init.min.js"></script>
For mobile app case, a new parameter must exist in the loading script
mobile:true
So the loading script would be as below
<script>
window.GbLoadInit = function(){
GbSdk.init({
playerUniqueId: '{{playerUniqueId}}',
lang: 'en',
playerAttributes:{},
APIKey: '{{Your_API_Key}}',
mobile:true
});
};
</script>
<script defer src="https://assets.gameball.co/widget/js/gameball-init.min.js"></script>

Pass user data to your Webview

The widget will display player's profile depending on the passed parameters to the init script. In order to pass player's data from your mobile app to Webview\Gameball's widget, there are two options depending on your framework capabilities.
If the used framework supports passing params\variables to Webview you can pass logged in user profile data directly to the Webview and inject them to Gameball widget loading script.
The other option is to pass players data to Gameball loading script via query strings while loading Webview as below example
https://yourdomain.com/webview-address?playerUniqueId={{playerUniqueId}}&displayName={{displayName}}
Once the data is added to the query string, you can use JavaScript to retrieve the data and pass it to the Gameball widget script. Here's an example of how you can do this:
<script>
// Get the query string parameters
const queryString = window.location.search;
const urlParams = new URLSearchParams(queryString);
// Get the user's email and display name from the query string
const playerUniqueId= urlParams.get('playerUniqueId');
const userDisplayName = urlParams.get('displayname');
window.GbLoadInit = function(){
GbSdk.init({
playerUniqueId: {{playerUniqueId}},
mobile:true,
playerAttributes: {
displayName: {{displayName}}
},
lang: 'en',
APIKey: '{{Your_API_Key}}'
});
};
</script>
By following the steps outlined above, you can easily pass user data to the widget script and provide your users with a seamless and personalized experience.
If you choose to go with using the pre-built widget in a Webview. You need to take care of the Webview interactions within your app. How the user can navigate from and to the Webview easily. We recommend showing the Webview as a modal with a back button on top.

Receive Gameball notifications

Gameball webhooks can be used to avail push notifications for mobile users. This can be done by webhook subscriptions to receive notifications for particular events in Gameball. After you have subscribed to a webhook, your app can execute a specific code immediately after specific events occur in Gameball. Common webhook use cases include sending notifications to IM clients and pagers

Handle Referrals

Gameball uses Firebase to generate dynamic links to support referrals. Hence Firebase dependency must be used in your mobile app
Before you start, you must configure your Firebase on your Gameball account. Follow the steps in Configure your Firebase account on Gameball for mobile friends referral links article in our Help Center to configure your Firebase account on Gameball.
Dynamic Links are smart URLs that allow you to send existing and potential users to any location within your app. They survive the app install process, so even new users see the content they're looking for when they open the app for the first time.
Once you've configured Firebase within your Gameball dashboard, Gameball will automatically create a unique referral link for each player. This referral link includes the player's unique referral code and can be shared with friends to refer them to your mobile app.
This referral link is generated dynamically and can be accessed via Gameball profile widget. It can also be accessed programmatically using the Gameball Get Player API within its response as below snippet.
{
"playerUniqueId":"player456",
...
....
"dynamicReferralLink":"https://yourapp.dynamiclink.link",
....
....
...
}
Depending on your desired experience. You can choose to show the referral link within profile page within your app so the users can locate it and share it within their network.
Now that you have allowed your user locate and share their referral links. Below is a step by step guide on how to listen to referral registration and notify Gameball to track and reward.
  1. 1.
    First, you'll need to set up Firebase within your mobile app.
  2. 2.
    After setting Firebase within your app and configuring Firebase from Gameball's dashboard, you'll need to listen to deep links query parameters within your app. When a user clicks on a Firebase Dynamic Link that includes the GBReferral parameter, the GBReferral parameter will be included in the deep link query parameters. This parameter contains the referral information that you'll need to send to Gameball to track referrals.
Here's an example of how you can listen to deep links query parameters and locate the GBReferral parameter in your mobile app:
// Listen for incoming Firebase Dynamic Links
Firebase.dynamicLinks().getDynamicLink { (dynamicLink, error) in
guard let dynamicLink = dynamicLink,
let deepLink = dynamicLink.url,
let queryItems = URLComponents(url: deepLink, resolvingAgainstBaseURL: true)?.queryItems else {
return
}
// Locate the GBReferral parameter
if let gbReferral = queryItems.first(where: { $0.name == "GBReferral" })?.value {
// Track the referral in your Gameball account
// ...
}
}
Once you have located the GBReferral parameter within a dynamic link. You will need to send its value and send along with the Create Player API that is being executed for the newly created referred player.
The below sample body for the Create Player API creates a new player with player unique id {referred_player_id} that has been referred by the player who owns the code of 001122 captured form the dynamic link
{
"playerUniqueId":"referred_player_id",
"referrerCode": "001122",
}