Unreal

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

Unreal SDK Integration

Follow the steps below to integrate the ByteBrew SDK or watch the tutorial video for a step by step walkthrough:

infoNote ByteBrew supports Android 5.1 and above & iOS version 9.0 and above. ByteBrew SDK is compatible with iOS 14 updates.

Step 1

Import ByteBrew SDK

Extract the ByteBrewSDK folder and copy it to your project's Plugins folder.

Step 2

Restart Your Unreal Editor

Restart your Unreal project to rebuild the plugin.

Step 3

Enable ByteBrew Plugin

Go to Edit > Plugins and make sure Other > ByteBrewSDK is enabled.

Step 4

Additional Steps for C++ integration

Create the ByteBrew GameObject by following the steps below:

Open your project's Build.cs file located at project_root/Source/Project_Name/Project_Name.Build.cs.

Add "ByteBrewSDK" to PublicDependencyModuleNames. It should look something like this:

                                
                                PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "ByteBrewSDK" });

Add "Settings" and "Launch" to PrivateIncludePathModuleNames. If it's not there, just add it below PublicDependencyModuleNames and/or PrivateDependencyModuleNames.

                                
                                    PrivateIncludePathModuleNames.AddRange(new string[] { "Settings", "Launch" });

Add #include "ByteBrewSDKInterface.h" to the top of your C++ header file.

notification_importantImportantPlace your initialization on the first scene of your game. ByteBrew SDK does not support offline event caching.

Step 5

Go to your ByteBrew Dashboard

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

Step 6

Initialize ByteBrew

After inputing your Game IDs and SDK Key, initialize ByteBrew using the code below at the beginning of your game to start capturing sessions and events:

                                
                                
                                
                            FString engineVersion = TEXT("unreal");
                            FString buildVersion = TEXT("1.0");
                                
                                #if PLATFORM_IOS
                                
                                    FString gameKey = TEXT("ios_game_key");
                                    FString secretKey = TEXT("ios_secret_key");
                                
                                    UByteBrewSDKInterface::InitializeByteBrew(gameKey, secretKey, engineVersion, buildVersion);
                                
                                #elif PLATFORM_ANDROID
                                
                                    FString gameKey = TEXT("android_game_key");
                                    FString secretKey = TEXT("android_secret_key");
                                
                                    UByteBrewSDKInterface::InitializeByteBrew(gameKey, secretKey, engineVersion, buildVersion);
                                
                                #endif

Step 7

Disable Android File Server

If you have the Android File Server plugin enabled (it might be enabled by default), you need to disable "use Android File Server".

Step 8

Blueprints (Optional)

ByteBrew offers the ability to use Blueprints as well instead of C++ in your Unreal Project.

infoNote You should also now be able to access the ByteBrew category when creating blueprints.

Step 9

Exporting iOS Requirements

To export for iOS, ByteBrew requires the following three (3) iOS Frameworks:

Security.Framework

AdServices.Framework

AdSupport.Framework

Each of these listed frameworks should be implemented in your final xcode project as frameworks.

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 (1) spaces, (2) periods ".", or (3) colons ":" in your custom events. As an alternative to spaces in custom events, use "_". Ex. "key_name=value;".

Custom event names that include (1) spaces, (2) periods "." or (3) colons ":" will not be processed on the dashboard. These events are unrecognized by ByteBrew and antipattern to ByteBrew's event structure.

For parameters under custom events, do not use spaces.

Basic Custom Event:

                                

                                
//Basic Custom Event without any sub-parameters
FString eventName = TEXT("test_event");
UByteBrewSDKInterface::NewCustomEvent(eventName);

Custom Event Tracking Method:

                                
                                    //Custom Event Format with sub-parameters
                                    FString eventName = TEXT("test_event");
                                    UByteBrewSDKInterface::NewCustomEventWithStringValue(eventName, TEXT("key_name1=value1;key_name2=value2;key_name3=value3;key_name4=value4;"));

                                    //Example Event
                                    FString exampleName = TEXT("LevelStarted");
                                    UByteBrewSDKInterface::NewCustomEventWithStringValue(exampleName, TEXT("level=25;character=AlienSpaceMan;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 watching the tutorial video or 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 use the IsByteBrewInitialized callback in the SDK to determine if the ByteBrew SDK has finished initialization before calling to get/update Remote Configs.

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 Remote Config Loader 
                                UByteBrewSDKInterface::LoadRemoteConfigs();


                                //Check if the remote configs are ready and set
                                bool bHasRemoteConfigsBeenSet = UByteBrewSDKInterface::HasRemoteConfigsBeenSet();

Retrieve the Configs

Once the loader 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
                                FString remoteConfigValue = UByteBrewSDKInterface::RetrieveRemoteConfigValue(TEXT("key"), TEXT("default_value"));

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 or watch the tutorial video series.

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

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:

                                
                                
                                UByteBrewSDKInterface::StartPushNotifications();

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.

Step 3

Specific Push Notification for Unreal:

If your Unreal Engine is built from the Github source

Open project settings (Edit > Project Settings).

Under Platforms > iOS, under the "Online" section, enable "Enable Remote Notifications Support".

If your Unreal Engine is NOT built from the Github source

Close the Unreal editor if it's open.

Open your DefaultEngine.ini config file located at project_root/Config/DefaultEngine.ini.

Find the section with the heading [/Script/IOSRuntimeSettings.IOSRuntimeSettings].

Add this line: bEnableRemoteNotificationsSupport=True

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"/>

Push Notification Xcode Export Additions (Required iOS Only)

For sending notifications to iOS devices, follow the additional required steps below on Xcode:

infoNote For the best step by step walkthrough on push notification integration, watch the video tutorial series on the ByteBrew Youtube Channel.

Step 1

Add UserNotifications.framework

Add UserNotifications.framework to the frameworks and libraries in Xcode.

Step 2

Add Capabilities

Press "+ Capability" and add the following capabilities listed in steps 3 and 4 below.

Step 3

Add "Background Modes" and under that section, checkmark "Remote Notifications

Step 4

Add "Push 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 or watch our tutorial video.

Track Basic In-App Purchases

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

                                
                                
   
                                UByteBrewSDKInterface::TrackInAppPurchaseEvent(TEXT("Apple App Store"), TEXT("USD"), 19.99f, TEXT("currencyPack01"), TEXT("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.

infoNote Using this methods will also track the purchases. You do not not need to track basic purchases and use the validation callback. Using both methods will cause your purchases to double.

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.

                                
                                
   
                                    //JSON Format ex. string json = "{\"firstname\":\"john\", \"lastname\":\"doe\",\"age\":30}";

                                    //Retrieve the iOS receipt from the purchase event that occurs. We will validate it server side so you can view valid purchases in you dashboard.
                                    FString iosReciept = "...";
                                    UByteBrewSDKInterface::TrackAppleInAppPurchaseEvent(TEXT("Apple App Store"), TEXT("USD"), 19.99f, TEXT("currencyPack01"), TEXT("Currencies"), iosReciept);

                                    //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.
                                    FString googleReciept = "...";
                                    FString googleSignature = "...";
                                    UByteBrewSDKInterface::TrackGoogleInAppPurchaseEvent(TEXT("Google Play Store"), TEXT("USD"), 19.99f, TEXT("currencyPack01"), TEXT("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, Location of the placement, ad unit ID, and Network
                                UByteBrewSDKInterface::TrackAdEventWithAdIDAndProvider(EByteBrewAdType::Banner, TEXT("ad_location"), TEXT("ad_id"), TEXT("ad_provider"));

                                //Some ad event paramters can be ommited like so
                                UByteBrewSDKInterface::TrackAdEvent(EByteBrewAdType::Interstitial, TEXT("ad_location"));
                                UByteBrewSDKInterface::TrackAdEventWithAdID(EByteBrewAdType::Reward, TEXT("ad_location"), TEXT("ad_id"));

Custom User Data Attributes

tag

Data attributes are tags in the SDK that you can give a user to define them more specifically on the dashboard when filtering. For example, you can use data attributes to tag to users to build player segments to send targeted push notifications. If you are looking to update values on users at certain locations of your game, then use Custom Events with subparamters to track that type of update. See the following code snippets for examples on how to use Custom User Data Attributes:

infoNote Custom Data Attributes should not be spammed or used to continuoisly update a set of values a single user. If our system detects or tracks that your game(s) are spamming this method, it will automatically turn off your Custom Data Attribute tracking.

                                
                                
                                
                                    UByteBrewSDKInterface::SetCustomData(TEXT("key"), TEXT("value"));
                                    UByteBrewSDKInterface::SetCustomDataFloat(TEXT("key_float"), 123.45f);
                                    UByteBrewSDKInterface::SetCustomDataInt(TEXT("key_int"), 42);
                                    UByteBrewSDKInterface::SetCustomDataBool(TEXT("key_bool"), true);

Progression Event Tracking

tag

Progression events are a great way to track linear event stages in your game to measure how players are transitioning through levels or worlds. See below for the list of progression event parameters and code snippets for progression events.

ProgressionType

The type of progression event. Must be one the following options:

fiber_manual_record

Started

fiber_manual_record

Completed

fiber_manual_record

Failed

Environment

Area or World in the game the event is located such as: Tutorial, Arena, or Level. You can choose how to define the environments in your game or app.

Stage

The stage of the environment that the event takes place in such as: king_arena, jungleLevel, or level_02. You can define how to define the stages in your game or app.

Value

The value of the event. This can be a string of float value.

                                

                                
                                    //Example Progression event where the user started a tutorial in arena 0 or first arena
                                    UByteBrewSDKInterface::NewProgressionEvent(EByteBrewProgressionType::Started, TEXT("Tutorial"), TEXT("arena0"));

                                    //Example progression event where the user has completed the kings arena and could be rewarded with 3 crowns
                                    UByteBrewSDKInterface::NewProgressionEventWithFloatValue(EByteBrewProgressionType::Completed, TEXT("Arena"), TEXT("kings_arena"), 123.45f);

                                    //Basic Example of Started Progression event with basic levels
                                    UByteBrewSDKInterface::NewProgressionEvent(EByteBrewProgressionType::Started, TEXT("Levels"), TEXT("level_01"));

                                    //Basic Example of Completed Progression event with basic levels
                                    UByteBrewSDKInterface::NewProgressionEvent(EByteBrewProgressionType::Completed, TEXT("Levels"), TEXT("level_01"));

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
                                FString userID = UByteBrewSDKInterface::GetUserID();

Initialization Callback

tag

In the SDK, you can use an initialization callback to get a True/False boolean to determine if ByteBrew SDK has completed the initialization.

                                
                                
                                
                                bool bIsInitialized = UByteBrewSDKInterface::IsByteBrewInitialized();

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.

                                
                                
                                
                                UByteBrewSDKInterface::StopTracking();

ProGuard Setup for ByteBrew SDK

tag

If you have ProGuard or Minify enabled in your game, add the following to your proguard file.

                                
                                
                                
                                
                                
                                -keep class com.bytebrew.** {*; }

SDK FAQs

What could cause a 401 Error in my game code?

If you're receiving a 401 Error in your game code, re-confirm that you have correctly inputting all your game's information including: SDK Key, Game IDs, and Bundle ID.

Why am I not seeing Custom Events populate on the ByteBrew dashboard?

If you track custom events in the same scene you initialize the ByteBrew SDK, then there is a chance your custom events wont get tracked as the SDK might not be finished initializing. To solve this, use the Initialization callback in the SDK to determine when the SDK has finished initialization before tracking custom events.

Why am I not receiving Remote Configs?

If you call for remote configs within the same scene you initialize the ByteBrew SDK, then there is a chance your remote configs wont get loaded as the SDK might not be finished initializing. To solve this, use the Initialization callback in the SDK to determine when the SDK has finished initialization before calling remote configs.

What is the minimum OS versions required for ByteBrew SDK?

ByteBrew supports Android 5.1 and above & iOS version 9.0 and above.

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.

Can I send event to ByteBrew using a server?

No, all events that can be sent to ByteBrew are only from our SDK.

Need some help?

Join the ByteBrew Discord community to chat with our team and other developers on the platform.

Go to Discord arrow_outward

lightbulb Pro Tip Re-input your SDK Keys and Game IDs each time you update the ByteBrew SDK!