Android

Learn how to integrate ByteBrew's light-weight Android SDK.

Android SDK Integration

tag

Follow the steps below to integrate the ByteBrew SDK:

infoNote ByteBrew supports Android 5.1 and above.

Step 1

Import ByteBrew Android Library to your project

To import the aar file go to File -> New -> New Module and click import .jar/.aar package.

Make sure to add the package as a dependency to your project and implement the imported package.

Add these required dependencies to support ByteBrew:

                                
                                
             
                                implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0'
                                implementation 'com.google.firebase:firebase-messaging:23.0.0'
                                implementation 'com.android.installreferrer:installreferrer:2.2'

notification_importantImportantInitialize ByteBrew in the first activity of your app. ByteBrew does not support offline event caching.

Step 2

Go to your ByteBrew Dashboard

Go to your Game Settings page on the ByteBrew dashboard and locate your app keys listed on the dashboard. After finding your app keys, copy them.

Step 3

Initialize ByteBrew with your Game ID and Game Key

Initialize ByteBrew using the code below at the first activity of your game or app to start capturing sessions and events.

Input the corresponding Game ID and Game Key from the ByteBrew dashboard into their parameter fields.

                                
                                
    
                                // Initialize ByteBrew
                                ByteBrew.InitializeByteBrew("GAME_ID", "GAME_KEY", "ENGINE/PLATFORM (ex. Android Native)", this);
                                ByteBrewAds.initAds(MainActivity.this);

Setup Ads

tag smartphoneMobile Only

The ByteBrew SDK supports both Interstitial and Rewarded in-app ads.

Interstitial ads are full screen skippable video advertisements you can show in your app. Interstitial ads are typically shown during natural pauses in your app or game.

Rewarded ads are full screen, non-skippable video advertisements that provide a "rewarded" callback to deliver an in-app reward after the ad is completed. Rewarded ads are typically offered users an in-app reward in exchange for their engagement during the ad duration.

infoNote ByteBrew SDK must be initialized first before setting up ads.

Set Up Ads Listeners

The following shows the ad event listeners and method signatures you can utilize. It's recommended to setup guards to prevent subscribing multiple times to listeners.

notification_importantImportant Do not oversubscribe to unnecessary ad event listeners or subscribe multiple times to the same listeners.

                                

                                @Override
                                protected void onCreate(Bundle savedInstanceState) {
                                    super.onCreate(savedInstanceState);
                                    setContentView(R.layout.activity_main);

                                    ByteBrewAds.setAdInitEventListener(new AdInitEventListener() {
                                        @Override
                                        public void onAdsInitSuccess() {
                                            // We can now start loading ads (See next section for more details)
                                            ByteBrewAds.loadInterstitialCrossPromoAd(_BBInterstitialAdUnitId);
                                            ByteBrewAds.loadRewardedCrossPromoAd(_BBRewardedAdUnitId);
                                        }

                                        @Override
                                        public void onAdsInitFailure() {}
                                    });

                                    ByteBrewAds.setInterstitialAdLoadEventListener(new AdLoadEventListener() {
                                        @Override
                                        public void onAdLoaded(AdData adData) {}

                                        @Override
                                        public void onAdLoadError(String error, AdData adData) {}
                                    });

                                    ByteBrewAds.setInterstitialAdEventListener(new InterstitialAdEventListener() {
                                        @Override
                                        public void onAdStarted(AdData adData) {}

                                        @Override
                                        public void onAdCompleted(AdData adData) {}

                                        @Override
                                        public void onAdClicked(AdData adData) {}

                                        @Override
                                        public void onAdDismissed(AdData adData) {}

                                        @Override
                                        public void onAdError(String error, AdData adData) {}
                                    });

                                    ByteBrewAds.setRewardedAdLoadEventListener(new AdLoadEventListener() {
                                        @Override
                                        public void onAdLoaded(AdData adData) {}

                                        @Override
                                        public void onAdLoadError(String error, AdData adData) {}
                                    });

                                    ByteBrewAds.setRewardedAdEventListener(new RewardedAdEventListener() {
                                        @Override
                                        public void onAdStarted(AdData adData) {}

                                        @Override
                                        public void onAdCompleted(AdData adData) {}

                                        @Override
                                        public void onAdRewarded(AdData adData) {}

                                        @Override
                                        public void onAdClicked(AdData adData) {}

                                        @Override
                                        public void onAdDismissed(AdData adData) {}

                                        @Override
                                        public void onAdError(String error, AdData adData) {}
                                    });
                                }

Loading Ads

Ads are loaded by ad unit ID. The methods also optionally take a boolean to indicate whether or not the ad should be CTRL only or not.

infoNote If the boolean ctrlOnly parameter is not specified for any of these methods, it will default to false.

Interstitial Ads

Load an interstitial ad by calling:

                                
                                
                                ByteBrewAds.loadInterstitialCrossPromoAd(_BBInterstitialAdUnitId);

                                //This is a specific call to only load a Ctrl targetted ad.
                                ByteBrewAds.loadInterstitialCrossPromoAd(_BBInterstitialAdUnitId, ctrlOnly);

Rewarded Ads

Load a rewarded ad by calling:

                                
                                

                                ByteBrewAds.loadRewardedCrossPromoAd(_BBRewardedAdUnitId);

                                //This is a specific call to only load a Ctrl targetted ad.
                                ByteBrewAds.loadRewardedCrossPromoAd(_BBRewardedAdUnitId, ctrlOnly);

Showing Ads

Once an ad is loaded, you can show it by calling the appropriate Show method with the ad unit ID.

infoNote If the boolean ctrlOnly parameter is not specified for any of these methods, it will default to false.

Interstitial Ads

                                
                                
                                //**Check & Call Interstitial Ad**
                                //Check for Interstitial Ad
                                ByteBrewAds.isCrossPromoAdLoaded(_BBAdUnitId);
                                
                                //Show Interstitial Ad
                                ByteBrewAds.showInterstitialCrossPromoAd(_BBInterstitialAdUnitId, context);


                                //**Check & Call Interstitial Ctrl Ad**
                                //Check for Interstitial Ctrl Ad
                                ByteBrewAds.isCrossPromoAdLoaded(_BBAdUnitId, ctrlOnly);
                                
                                //Show Interstitial Ctrl Ad
                                ByteBrewAds.showInterstitialCrossPromoAd(_BBInterstitialAdUnitId, ctrlOnly, context);

Rewarded Ads

                                

                                //**Check & Call Rewarded Ad**
                                //Check for Rewarded Ad
                                ByteBrewAds.isCrossPromoAdLoaded(_BBAdUnitId);

                                //Show for Rewarded Ad
                                ByteBrewAds.showRewardedCrossPromoAd(_BBRewardedAdUnitId, context);

   
                                //**Check & Call Rewarded Ctrl Ad**
                                //Check for Rewarded Ctrl Ad
                                ByteBrewAds.isCrossPromoAdLoaded(_BBAdUnitId, ctrlOnly);

                                //Show Rewarded Ctrl Ad
                                ByteBrewAds.showRewardedCrossPromoAd(_BBRewardedAdUnitId, ctrlOnly, context);

Recommended Ad Setup

To capture both high-value users and also fill empty ad space, you can setup your ad implementation using the following structures:

infoNote Utilizing these code structures are the most effective ad strategy to maximize portfolio growth with ByteBrew Ctrl AI.

Interstitial Ads

                                
                                
                                //Call Ctrl targetted ad to capture high-value users
                                if (ByteBrewAds.isCrossPromoAdLoaded(_BBInterstitialAdUnitId, ctrlOnly))
                                {
                                    ByteBrewAds.showInterstitialCrossPromoAd(_BBInterstitialAdUnitId, ctrlOnly, context);
                                }
                                else if(YOUR_MONETIZATION_PARTNER_STATUS)
                                {
                                    //SHOW YOUR MONETIZATION PARTNER
                                }
                                else if (ByteBrewAds.isCrossPromoAdLoaded(_BBInterstitialAdUnitId)) //Check and show an ad
                                {
                                    //Call to fill empty ad space
                                    ByteBrewAds.showInterstitialCrossPromoAd(_BBInterstitialAdUnitId, context);
                                }

Rewarded Ads

                                
   
                                //Call Ctrl targetted ad to capture high-value users
                                if (ByteBrewAds.isCrossPromoAdLoaded(_BBInterstitialAdUnitId, ctrlOnly))
                                {
                                    ByteBrewAds.showRewardedCrossPromoAd(_BBRewardedAdUnitId, ctrlOnly, context);
                                }
                                else if(YOUR_MONETIZATION_PARTNER_STATUS)
                                {
                                    //SHOW YOUR MONETIZATION PARTNER
                                }
                                else if (ByteBrewAds.isCrossPromoAdLoaded(_BBInterstitialAdUnitId)) //Check and show an ad
                                {
                                    //Call to fill empty ad space
                                    ByteBrewAds.showRewardedCrossPromoAd(_BBRewardedAdUnitId, context);
                                }

Ad Initialization Status

You can check if the ads system is initialized by calling ByteBrewAds.IsAdsInitialized():

                                
                                
   
                                boolean adsInitialized = ByteBrewAds.isInitialized();

Custom Events Tracking

tag

Custom Events in ByteBrew enable you to deep dive across all of our extensive analytics dashboards. Continue below to learn how to integrate custom events.

Custom Events on ByteBrew allow for an unlimited number of key_name=value; sub-parameters under the custom event. For example, you can have a custom event called “level” that has a subparameter under the event named “levelnumber” and the values of that Level Number subparameter could be “1, 2, 3, 4, 5, etc.”. Additionally you could add in other subparameters for attributes inside the levels of your game, such as "powerups", to show the different equipment used in levels with parameter values "fireball, revive, doublepoints, etc.". The world is your oyster with custom events, so build as complex of an event system as you need for your game. To illustrate our custom event structure visually, see the following diagram:

notification_importantImportant Do not replicate or copy/paste event structures from other analytics providers to ByteBrew, this will lead to malformed event reporting. Follow ByteBrew's event structure in the following documentation.

Custom Events

See samples below to see how to code Custom Events:

notification_importantImportant Do not use special characters, such as (1) spaces, (2) periods ".", or (3) colons ":" in your custom events or parameters. As an alternative to spaces in custom events, use "_". Ex. "key_name=value;".

Custom event names and parameters that include special characters will not be processed on the dashboard. These events are unrecognized by ByteBrew and antipattern to ByteBrew's event structure.

Basic Custom Event:

                                

                                    //Basic Custom Event without any sub-parameters
                                    ByteBrew.NewCustomEvent("eventName");

                                    //Basic Custom Event with a sub-parameter
                                    ByteBrew.NewCustomEvent("CustomEventName", "key_name=value;");

                                    //Examples
                                    ByteBrew.NewCustomEvent("GamePurchaseVC", "currency=GOLD;amount=500;character=viking;");
                                    ByteBrew.NewCustomEvent("LevelCompleted", "level=25;character=viking;");

Dictionary Custom Event Tracking Method:

To easily add additional custom sub-parameters to an event with a dictionary method using string "key_name=value;" pairs shown below:

                                
                                
                                //Key Value format "key_name=value;"
                                //Custom Events can take multiple pairs, "key_name1=value1;key_name2=value2;key_name3=value3;"
                                ByteBrew.NewCustomEvent("level_started", "weapon=megablaster;powerup=extralife;");

Remote Configs & A/B Tests

tag

Remote Configs allow you to make updates to your app remotely without having to update your game's app store. Adding remote configs to your games are a fantastic way to be agile and send updates or patches to players instantly. Remote Configs are also utilized for creating A/B Tests on the platform.

When planning to integrate Remote Configs, We recommend implementing remote configs throughout all parts of your game to allow you to tweak and tune as you analyze your game performance data. See how to implement remote configs in your game by following the steps below:

infoNote If you are calling to get/update Remote Configs in the same scene as your ByteBrew initialization, it's recommended to add a 1-2 seciond wait before calling to get/update Remote Configs to allow ByteBrew to fully initialize.

notification_importantImportant Do not spam config calls in your app code. Apps that spam remote configs calls with behavior such as: calling configs each game frame, or rapidly firing multiple calls per user will be auto flagged and potentially paused.

Loading the Remote Configs

To use Remote Configs, you must first call for the config to get updated. You can call the below code whenever you want to update the configs:

                                
                                

                                    //Call the handler 
                                    ByteBrew.LoadRemoteConfigs(new RemoteConfigListener() {
                                        @Override
                                        public void RetrievedConfigs(boolean b) {
                                              //Do Whatever you want here once the config is updated
                                        }
                                    });
                                  
                                    //Check if the remote configs are ready and set
                                    ByteBrew.HasRemoteConfigsBeenSet();

Retrieve the Configs

Once the handler has finished, you can call the remote config method below:

infoNote Additionally, you can grab A/B Test keys and values using this method. If the user is part of the control group it won't return anything but the default parameter value set.

                                
          
                                //Call to get the key specific value and if the key doesn't exist it will return the default variable specified, like if the AB test user is in the control group
                                String value = ByteBrew.RetrieveRemoteConfigValue("dailyWeapon", "goldRevolver");

Push Notifications

tag

Using ByteBrew you can send cross-platform push notifications to your players around the globe. To get started with push notifications follow the steps below.

infoNote If you are using Push Notifications in ByteBrew, you must first call InitializeByteBrew before calling StartPushNotifications.

notification_importantImportantIn addition to setting up Push Notifications in the SDK, there is additional setup required on the ByteBrew dashboard to get up and running. Visit the Push Notifications documentation page for all the steps to get step.

Step 1

Integrate Push Notifications

Integrating Push Notifications with ByteBrew is super simple and only requires one line of code after initializing the ByteBrew SDK. See the Push Notification integration code line below:

                                
                                


                                    ByteBrew.StartPushNotifications(this);

Step 2

Create Push Notification App on the ByteBrew Dashboard

Go to the Push Notification dashboard on ByteBrew and create a new Push Notification App. See our Push Notification Dashboard documentation for step by step walkthroughs about this.

infoNote In order to create a push app, you must first create an game or app on the ByteBrew dashboard.

Push Notification Extra Settings (Optional Android Only)

Add a Custom Small Icon and Large Icon for push notifications.

infoNote The small icon automatically defaults to your app icon. We recommend that you add a small icon because your app icon may not appear correctly. If the large icon default is none, it will not show.

notification_importantImportantMake sure to add these icons to your res android folder. Keep note of the name of the icon, so you can set them in the dashboard when creating a notification.

Push Notification Android Manifest (Required Android Only)

notification_importantImportantIf your app targets Android API Level 33 and above, make sure your implement this manifest permission.

                                
                                    <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>

Track Purchases

tag

In ByteBrew SDK you can track all your game or apps in-app purchases to analyze your monetization performance on the dashboard. There are two ways to track purchases on ByteBrew. The first way is to use basic in-app purchase events. The second way is to use our real-time server-side purchase validation to validate real purchases vs. fraudulent transactions. See below to learn how to implement either method.

Track Basic In-App Purchases

To track in-app purchases in your game, use the below method:

                                                             
  
                                    ByteBrew.TrackInAppPurchaseEvent("Google Play Store", "USD", 5.99, "currencyPack01", "Currencies");

Track Validated Purchases

On ByteBrew, we offer a real-time server-side purchase validation to stop purchase fraud from client-side purchase receipt tampering that takes place in mobile games and apps. To utilize this validation you have two options: (1) a method with a callback to retrieve if a purchase was valid and (2) a method just to validate purchases without a callback. Follow below sections for code snippets for each function:

infoNote To help avoid any common mistakes made during integration of purchases follow the below:

fiber_manual_record

You do not not need to use track using both the basic tracking purchase method and purchases validation methods. The purchase validation method also tracks purchases. Using both methods will cause your purchases to double.

Purchase Validation with Callback

To track validated in-app purchases utilize the platform specific method. Using this method will create a purchase callback that will return a payload with the purchases details and verification status. See below for the Return Results and message definitions:

notification_importantImportantMake sure the receipts have correct JSON string formatting.

                                


                                //Retrieve the Android receipt and Signature from the purchase event that occurs. We will validate it server side so you can view valid purchases in you dashboard.
                                String googleReciept = "...";
                                String googleSignature = "...";
                                ByteBrew.ValidateGoogleInAppPurchaseEvent("Google Play Store", "USD", 5.99, "currencyPack01", "Currencies", googleReciept, googleSignature, new PurchaseResponseListener() {
                                    @Override
                                    public void purchaseValidated(ByteBrewPurchaseResult byteBrewPurchaseResult) {
                                        Log.d("Purchase Processed: ", String.valueOf(byteBrewPurchaseResult.isPurchaseProcessed())); //Boolean telling if the purchase even went to the server to get checked
                                        Log.d("Purchase itemID: ", byteBrewPurchaseResult.getItemID());                              //Product/Item ID of the purchase processed
                                        Log.d("Purchase is Real: ", String.valueOf(byteBrewPurchaseResult.isPurchaseValid()));       //Boolean signaling if the purchase is real or fake
                                        Log.d("Process Message: ", String.valueOf(byteBrewPurchaseResult.getMessage()));             //Message from the server telling the explaination behind the decision
                                    }
                                });

Returned Results:

The following table are the possible returning results:

fiber_manual_record

purchaseProcessed: Boolean communicating if the purchase was processed by the server.

fiber_manual_record

isValid: Boolean telling if the purchase is Real or Fake.

Returned Results Message:

In addition to the Return Result you will also recieve a message. See below for possible output messages and their definition:

"Validation Successful, real purchase.": This means that the message as a real purchase.

"Validation Failed, fake purchase.": This means that the purchase is fake or fraudulent.

"Error validating receipt, check game configs.": This message means that there might be an issue with the implementation. Check to make sure that the purchaseProcessed boolean is True and go to your game settings on the ByteBrew dashboard to update your Apple App Shared Secret and Google Play License Key.

Purchase Validation without Callback

To track in-app purchases using our validation system without looking for the purchase callback, utilize the platform specific method code snippets below:

notification_importantImportantMake sure the receipts have correct JSON string formatting.

                                


                                    //Retrieve the Android receipt and Signature from the purchase event that occurs. We will validate it server side so you can view valid purchases in you dashboard.
                                    String googleReciept = "...";
                                    String googleSignature = "...";
                                    ByteBrew.TrackGoogleInAppPurchaseEvent("Google Play Store", "USD", 5.99, "currencyPack01", "Currencies", googleReciept, googleSignature);

Ad Tracking Event

tag

Using ByteBrew you can track your game's or app's ad events. Tracking Ad Events will enable you to see breakdowns of your ads in the monetization dashboard. See the code snippets below to learn how to track ad events:

infoNoteTracking Ad Events in the ByteBrew SDK is required for visualizing pLTV and pROAS calculations on the Attribution dashboard.

                                
                                

                                    // Record the Placement Type, Provider of the ad, ad unit name, and revenue of the impression
                                    ByteBrew.TrackAdEvent(ByteBrewAdType.Interstitial, "Google AdMob", "Interstitial_Unit_Name", 0.00074145);
                                    ByteBrew.TrackAdEvent(ByteBrewAdType.Reward, "Applovin Ads", "Reward_Unit_Name", 0.005562);

                                    //Add your ad units placement location in your game to breakdown your impression more.
                                    ByteBrew.TrackAdEvent(ByteBrewAdType.Interstitial, "Google AdMob", "Interstitial_Unit_Name", "Interstitial_EndOfLevel", 0.0024145);

Data Attributes

tag

Data Attributes are tags in the SDK that you can give a user to define them for live ops functions. For example, you can use Data Attributes to tag user to build player segments to send targeted remote configs and push notifications. If you are looking to tag users for tracking and filtering, then use Custom Events with subparamters to track that type of update. See the following code snippets for examples on how to use Data Attributes:

infoNote Data Attributes should not be spammed or used to continuously update a set of values for a single user. If our system detects or tracks that your app(s) are spamming this method, it will automatically turn off your Data Attribute tracking. See list for most common forms of spamming:

fiber_manual_record

Sending a high frequency of updates per second or per user.

fiber_manual_record

Using Data Attributes like Custom Events.

fiber_manual_record

Sending updates to Data Attributes in bulk by updating all attributes at once instead of one value that was changed.

fiber_manual_record

Sending unnecessary updates by updating Data Attributes with repeated values.

fiber_manual_record

Using Data Attributes for user tracking or filtering.

                                

                                ByteBrew.SetCustomData("dundees", 3);
                                ByteBrew.SetCustomData("loves_the_office", true);

Get User ID

tag

GetUserID method in the SDK enables you to grab the current User ID of the user in your game. This is a handy method for finding the ID for a user you want to send a specific push notification to.

                                
                          

                                    // Get the string userID
                                    ByteBrew.GetUserID();

Stop Tracking Current User

tag

In the ByteBrew SDK, you have the option to stop tracking any user in your game by calling the ByteBrew StopTracking method. This will immediately stop and disable any tracking for a user. As another alternative method to disabling tracking, you can build your own consent pop-up prompt screen in your game or app and delay the initialization of ByteBrew SDK until your user has consented/agreed to your prompt.

                                

                                    ByteBrew.StopTracking();

SDK FAQs

What is the minimum OS versions required for ByteBrew SDK?

ByteBrew supports Android 5.1 and above.

What events does ByteBrew automatically track?

ByteBrew has standardized events that are automatically tracked such as: install events and session events. These events are used throughout the platform to automatically calculate out-of-the-box metrics like: session length, playtime, retention and more.

Does ByteBrew track offline users?

here are several reasons ByteBrew does not cache offline player data such as:
(1) App File Size: For games tracking many parts of their apps, users playing offline will generate a significant file size of cached data that will inflate the app size on the device.
(2) Reduce App Crashes: If the storage of offline data becomes too large, the device will not be able to open the app on lower end devices and cause a potential app crash. ByteBrew is designed to make sure those issues do not exist for your game.
(3) Data Accuracy Tampering: Cached data from historical game session will get uploaded into the system the next time the user comes back online. This mean malicious users can tamper with your app's data, leading to potential issues with accurate reporting for you to operate from.

Can I use two push notification providers at once?

No, you can only use one push notification service or provider to send notifications at one time. However, if you are only using ByteBrew for our other services, then you can use another platform's push notifications SDK while still using ByteBrew SDK without any issues.

Is there any callback needed for Push Notifications?

No, Push Notifications has it's own internal callback, so no other callback is necessary.

What is the minimum Android API version for ByteBrew?

API Level 22 (Android 5.1)

How long does it take for my Configs or my A/B Test to deliver to my players?

A/B Tests deliver configs using your Remote Configs integration. Remote Configs delivered in milliseconds to your players after the ByteBrew SDK is initialized.

Should I convert revenue to USD?

Yes, whether tracking in-app purchases or using Custom Events that send revenue parameters, the revenue you send should be in USD.

lightbulb Pro Tip Initialize ByteBrew in the first activity of your app or game.