Unity | Node.js | Getting Started

Full Guide with Unity & Node.js

⏱️ 45-minute integration Sample integration between the frontend and backend. If you use a different language the concepts here should still apply and easy to follow.

Getting Started

In this scenario, we will be using the following stack:

Unity as our game engine
Node.js for our backend web server

Prerequisites

Before we get started here, let's cover some requirements that are need to get going. Don't worry, we go over each step here in detail. Feel free to skip around using the aside navigation.

Minimum Unity version: "unity": "2021.3"
Bolt Sandbox Account Make sure to check your spam folder for the verification email
This is where you'll get your API Key for your web server integration!
Bolt Unity SDK
Your Game's Backend Web Server Integration
Deep Links Enabled for your iOS Build

💹 Do You Like Diagrams?

We've got a high-level IAP sequence diagram that we will be updating as we iterate on our release(s). You can check that out over here!

Your Bolt Sandbox Dashboard

Head on over to the Bolt Sandbox Dashboard and sign up for your Sandbox Account.

Once you're in, finish up the on-boarding steps to make sure you get a production-esque experience.

Getting through the Tasks (Tax Compliance)

⚠️ Setup Tax Compliance Provider

We are currently working on automating or bypassing the Tax Setup in Sandbox accounts. For now, we need to manually flag this as complete.

If you have any issues with on-boarding completion, please contact us directly and we will assist you with the configuration step. Thank you!

Your API Key

Go into your Administration section to access you API key(s) and secret(s).

⚠️ Protect Your Keys!

When building out your web service integration, be sure to securely store your API key(s) in a non-public .env. Here is a helpful Strapi article touching upon that.

You will also need your Publishabke Key to generate your Payment URL.

Webhooks

It's also important to get at least one webhook registered for your game studio.

Your First Payment Link!

Here is an example cURL request to dynamically generate a Payment URL:

Request

curl --location 'https://api-sandbox.boltapp.com/v1/gaming/payment_links' \
--header 'x-api-key: {BOLT_API_KEY}' \
--header 'x-publishable-key: {BOLT_PUBLISHABLE_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "game_id": "{YOUR_GAME_ID}",
    "user_id": "USER_ID",
    "redirect_url": "bubble-merge://bolt-webcheckout/success",
    "item": {
        "price": 699,
        "name": "Gems Pack",
        "currency": "USD"
    },
    "metadata": {
        "beamable_id": "9876543210",
        "greeting": "Hello World!"
    }
}'

Response

{
	"id": "8PFm6ZzP7hX22vpeEwGoXs",
	"link": "https://knights-of-valor-bolt.c-staging.boltapp.com/c?u=Fv8ZMmDmRb86C4XRiB92x2&publishable_key=_Kq5XZXqaLiS.3TOhnz9Wmacb.9c59b297d066e94294895dd8617ad5d9d8ffc530fe1d36f8ed6d624a4f7855ae"
}

For more information on generating Payment URLs from your web server using the Bolt API, please dig in here.

If you're a Unity pro, you can just skip right through this and go source dive our GitHub repo. Otherwise, take your time and follow this guide and corresponding links to get better acquainted with the Bolt Unity SDK.

Download and install the Bolt Unity SDK [Read More]
Set up an HTTP client (or use your existing one) within Unity for communicating with your web server [Read More]
Implement the method calls to initate and open the native browser with Web Checkout via Bolt Payment URL's [Read More]
Enable deep links within your iOS build (Android coming soon)
Hook into the Bolt Unity SDK event loop to handle success/failures from the browser; we have some raw source code with deep link integration examples here.
Test, deploy, and game on!

Web Server Integration

We are going to be using Node.js as our backend server. It's imperative that we have a minimal of two endpoints for this to work:

Payment URL Endpoint - This is the endpoint that your game will call to get a Payment URL from Bolt using the Bolt API.
Transaction Webhook - This is the endpoint that Bolt will call to notify your game of a transaction's status.

🔥 Example Game Web Server

We have an entire GitHub repo showcasing how to set up a game's web server.

Payment URL Endpoint

Here is an example using Node.js and the fetch() API approach to get a checkout link from Bolt using the Bolt API.

⚠️ Important

The fetch() API is only available in Node.js 18.0.0 or higher.

Node.js

require('dotenv').config()

const bodyPayload = {
  game_id: 'game-01234567890',
  user_id: 'user-9876543210',
  return_url: 'bubble-merge://bolt-webcheckout/success',
  item: {
    title: 'Gems',
    price: 999,
    currency: 'USD'
  },
  metadata: {
    beamable_id: '9876543210',
    greeting: 'Hello World!'
  }
}

// Because these just don't exist in your repo, right?
const boltKey = process.env.BOLT_API_KEY
const boltPublishKey = process.env.BOLT_PUBLISH_KEY

const response = await fetch('https://api-sandbox.boltapp.com/v1/gaming/payment_links', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': `${boltKey}`,
    'X-Publishable-Key': `${boltPublishKey}`
  },
  body: JSON.stringify(bodyPayload)
})

const data = await response.json()

Example Response

🥚 Stub Out a Reponse?

If you are wanting to stub out the checkout link to get started in your game's code base while development on your backend is in progress, you can use a test/no-expiry link from our Bolt treasure chest. See below.

Response

{
  "id": "RsT4cu4KoeF7rbZjxVajy6",
  "link": "https://bolt.c-staging.boltapp.com/o?order_token=4c3e736d0e5020df4bfddabbdef7f00c5ac54b752d7d883256588351265e2e96"
}

Deep Links

Deep links are a way to open your game from a URL, specifically the return_url that you provide to Bolt in your API call. This is a requirement for Bolt's Unity SDK to work on iOS.

⚠️ Tip

We pass back the metadata that you provide to Bolt in your API call as a base64 encoded query parameter in the return_url.

Testing Purchases

Go ahead and do the above, then test with a fake credit card: 4111 1111 1111 1111

Unity | Node.js | Getting Started

On this page