Bolt Unity SDK

What is this?

This SDK provides native Unity support for Bolt Ads and Web Payments. We also support other platforms:

JavaScript Javascript SDK	Unity This Repo	Unreal Engine Unreal SDK
iOS Coming Soon 🚧	Android Coming Soon 🚧

Chat with us on Discord for help and inquiries!

📚 Documentation

For further documentation and API reference visit our Quickstart guide.

💰 Why Bolt

Only with Bolt you get 2.1% + $0.30 on all transactions. That's 10x better than traditional app stores which take 30% of your revenue! That's the fair and transparent pricing you get with using Bolt.

Bolt’s fees are subject to change but will remain highly competitive. For the latest rates, see Bolt Pricing. For details, review the End User Terms and Conditions.

🛠️ Prerequisites

You need 3 things to get started:

1. Existing App: You will need an application in the same platform as this SDK
2. Backend Server: You will need to bring your own backend server (any language)
3. Bolt Merchant Account: Dashboard access to manage your store (sign up or log in)
4. UniWebViewAdService.cs Unity plugin supporting iOS and Android in-game webviews

📦 Installation

Step 0: Install UniWebView

UniWebView is a Unity plugin supporting in-game webviews for iOS and Android mobile games. In order to install, please refer to the UniWebView installation guide here.

Note: You are open to follow the installation method of your preference. Most convenient options would be through the Unity Asset Store or UniWebView's own web store.

Step 1: Install the Unity SDK

Note: For any of these options you can specify a specific version by appending it to the URL with a hashtag, e.g. https://github.com/BoltApp/bolt-unity-sdk.git#v0.0.5 will pin v0.0.5

Option 1: Using manifest.json (Recommended)

1. Open your Unity project
2. Navigate to the Packages folder in your project root
3. Open the manifest.json file in a text editor
4. Add the Bolt SDK dependency to the dependencies section:

{
  "dependencies": {
    "com.bolt.sdk": "https://github.com/BoltApp/bolt-unity-sdk.git#main",
    // ... other dependencies
  }
}

5. Save the file - Unity will automatically download and import the package

Option 2: Using Package Manager UI

1. Open Package Manager in Unity (Window > Package Manager)
2. Click the "+" button in the top-left corner
3. Select "Add package from git URL"
4. Enter the repository URL: https://github.com/BoltApp/bolt-unity-sdk.git#main
5. Click "Add"

If you have any issues our discord support team will be happy to help.

Step 3: Update Unity Project Settings to Include New Plugins

Under your game's project settings, go to Player and make the following changes:

1. Find the Other Settings section, at the bottom of this section you will see Script Compilation
2. Add both BOLT_SDK and UNIWEBVIEW as scripting define symbols

Step 4: Add code to your game

The SDK includes sample integrations that you can import into your project via the Unity Package Manager.

1. In the Unity Editor, open Window > Package Manager.
2. Select the Bolt SDK package.
3. In the right-hand pane, find the Samples section and click Import next to the desired sample (e.g., AdsIntegration).

This will copy the sample files into your Assets/Samples folder.

Ads Integration

1. After importing the AdsIntegration sample, move the files from Assets/Samples/Bolt SDK/<version>/AdsIntegration into your game's source code folders (e.g., Assets/Scripts/).

2. Update both BoltClient.cs and UniWebViewAdService.cs so their namespaces reference your project's paths

3. Update BoltClient.cs in the InitializeBoltSDK() method (around lines 13-14)

• gameId - Your Bolt game ID (replace "com.myapp.test")
• publishableKey - Your Bolt publishable key (replace "example.publishable.key")
• Environment - Set to BoltConfig.Environment.Development, BoltConfig.Environment.Sandbox, or BoltConfig.Environment.Production (currently defaults to Sandbox on line 36)

Step 4: Add the BoltClient to Your Scene

1. Create an empty GameObject in your scene
2. Add the BoltClient component to it
3. The client will initialize automatically on Start()

Step 5: Unity Button Attachment for Displaying Ads

To display an ad when a user clicks a button, attach a "listener" via code. This allows you to pass important tracking information to the Bolt ad server.

Create a new file to handle all button clicks. Similar to Step 4, attach this file to an empty GameObject in your scene. Inside this script's Start method, add one listener per unique button asset. Here's an example:

using UnityEngine;
using UnityEngine.UI;
using BoltApp.Samples; // Replace with your namespace

public class MyGameMenu : MonoBehaviour
{
    public Button newLifeButton;
    public Button bonusButton;

    void Start()
    {
        // Attach a listener to each button
        newLifeButton.onClick.AddListener(() => {
            BoltClient.Instance.ShowAd("new_life_1", AdSurface.GameOver);
        });
        bonusButton.onClick.AddListener(() => {
            BoltClient.Instance.ShowAd("bonus_1", AdSurface.MainMenu);
        });
    }
}

Why use this instead of the Unity Inspector?

The Unity Inspector only supports calling functions with zero or one argument (like just a string). Since ShowAd requires both a Button ID and an Ad Surface for analytics, using AddListener in code is the best way to handle multiple parameters.

Analytics Metadata

By passing these two parameters, you can track exactly where and which button triggered an ad:

• Button ID: A unique string of your choosing to identify which specific UI element the user interacted with.
• Ad Surface: A categorized location in your game. Using these constants helps group your data:
  • AdSurface.MainMenu
  • AdSurface.Shop
  • AdSurface.LevelComplete
  • AdSurface.GameOver
  • AdSurface.Other
  • AdSurface.Custom("your_custom_surface")

Step 6: Handle Ad Lifecycle Events

The OnAdOpened() and OnAdCompleted() methods in BoltClient allow you to add things like UI updates, game state management, player rewards, etc.

The ad page uses UniWebView's Channel Messaging API to send a callback when the user closes a given ad.

• When the claim button is clicked, the ad page calls window.uniwebview.send('bolt-gaming-issue-reward', ...)
• UniWebViewAdService catches this via OnChannelMessageReceived
• This fires the onAdCompleted event in your BoltClient

What this means for you:

• The callback is handled automatically
• To handle rewards logic, update BoltClient's OnAdCompleted() (line 95)

Gotchas and Important Notes

1. UniWebViewAdService Must Be in Game Code

The SDK doesn't include UniWebView as a dependency. Your game provides the implementation via IAdWebViewService.

Copy UniWebViewAdService.cs anywhere that your BoltClient.cs file can reference, not the SDK folder.

2. Idepmotency

While not necessary, it is safe to call the SDK's preloadAd function multiple times. The webview is created once and reused. Only one ad can be active at a time. If you call ShowAd while an ad is already showing, the previous session will be replaced.

Web Payments

Here are some details on the payments integration which has some key differences to the Ads example above.

Integration Examples

Integration examples are also provided in the Samples~/ folder.

• BoltBasicExample: will showcase how to initialize the client and check for pending transactions
• BoltDeepLinkExample: will showcase how to handle deep links back into the application.

Backend Integration

You will need to bring your own backend server to complete integration for web payments.

• Quickstart: View our quickstart guide to get the API running
• Example Server: We also have a sample server in NodeJS for your reference during implementation

Need help?

Got questions, roadmap suggestions, or requesting new SDKs?
Get help and chat with us about anything on Discord

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.