Unity SDK Integration Guide

Overview

This document provides step-by-step instructions to help you integrate the SDK into your project. For further assistance, you can refer to the CheckoutSample file.

Prerequisites

Before starting, you need to gather some information from the Appcharge dashboard:

  • Public Publisher Token: Navigate to Admin -> Integration -> Checkout Public Key to get your public token.

Steps to Integrate Appcharge SDK

1. Download the SDK

Download the latest release of Appcharge's Unity SDK (contact Appcharge team). The package contains a ReadMe file including all of the needed information.

2. Import the SDK into Unity

  1. Open your Unity project.
  2. Go to Unity -> Assets -> Import Package.
  1. Select the downloaded SDK package.
  2. Click on All in the import menu, then select Import. This will add the Appcharge SDK code to your project.

3. Adding AppCharge's Dependencies

To add Appcharge's SDK Android dependencies to your project, you have to add a custom mainTemplate.gradle to your project.

  1. Enable Custom Gradle Template

Skip this if you already have a mainTemplate.gradle file in your project

Go to Player Settings > Android > Publishing Settings > Build > Custom Main Gradle Template, and mark the checkbox true.

  1. Add Dependencies to mainTemplate.gradle

Add the following code to your project mainTemplate.gradle file, under dependencies:

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    implementation("androidx.browser:browser:1.6.0")
}

Please note that if Android Auto Resolver is activated, it might manipulate this file.

4. Setup the AppChargeConfig File

  1. Locate the AppChargeConfig file in the folder Assets/Resources/AppCharge.
  2. In case the AppChargeConfig file is not presented, right click Create > Appcharge > ConfigFile
  3. Configure the following settings:
SettingDescription
EnvironmentChoose your desired environment. (Either Sandbox or Production)
Public Publisher TokenPaste your public token obtained from the Appcharge dashboard.
Show LoaderChoose if you want to display the visual loader when loading the checkout.
Show SuccessChoose if you want to display the default success screen after a successful transaction.
Canvas NameSpecify the name of the Canvas to be used for the Appcharge Checkout (The name of your canvas in the scene).

5. Initialize the SDK

Use gameObject to initialize the SDK, preferably at the start of your game.

gameObject can be any object in the scene. We suggest creating a new gameObject in your scene called AppchargeManager.

Example:

// Initialize Appcharge component
AppchargeManager.Init(gameObject);

Replace gameObject with the chosen GameObject.

6. Listen to SDK Events

The Appcharge checkout will fire the following front-end side events to enable realtime analytics for the publisher usage. Some events are purely analytical, whereas others will require actions on the publisher side.

The table below outlines each event and the recommended actions to take when they occur (if needed):

Property nameEvent nameDescriptionRecommended Action
OnLoadedloadedThe checkout has finished loadingClose the publisher's custom loading animation (if used)
OnOrderSuccessorderSuccessThe publisher has acknowledged that the player's account was awarded with the purchaseRun publisher customized successful purchase animation and resume game (if used)
OnOrderFailedorderFailThe award has failed, although the payment was successfulCheck server errors, don’t run success animation and resume game
OnClosecloseThe checkout was closed by the playerResume game or convince the player to stay in store
OnErrorerrorThe checkout throws general errorResume game or convince the player to stay in store

To handle events from the SDK, use the following code:

AppchargeManager.ListenToEvent(CheckoutEvents.OnLoaded, (Dictionary<string, string> args) =>
        {
            Debug.Log("Checkout loaded triggered: " + Utils.ConvertToString(args));
        });

Please refer to the Player Payment Real Time SDK Events Documentation for more information.

7. Configure Visual Loader

To use the Appcharge loader:

  1. Locate the AppChargeConfig file in the folder Assets/Resources/AppCharge.
  2. Turn on the loader toggle.

To use your own loader:

  1. Locate the AppChargeConfig file in the folder Assets/Resources/AppCharge.
  2. Turn off the loader toggle.
  3. Show your visual loader animation after calling AppchargeManager.OpenCheckout.
  4. Upon getting the OnLoaded event, remove your loader.

8. Launch the Checkout

Create a checkout model by using the following code snippet:

AppChargeCheckoutModel checkoutModel = new AppChargeCheckoutModel(...);

Parameters required for the checkout model:

ParameterTypeDescription
customerIdstringThe name of the customer
customerEmailstringCustomer email address
pricefloatOffer price (in cents)
currencystringOffer price currency. For example: "usd", "eur"
offerNamestringThe name of the offer
offerSkustringOffer's sku
offerAssetUrlstringAn image URL for the offer
offerDescriptionstringOffer's description

Add a set of items (bundle) as followed:

Note: At least one item must be included.

// Utilize the model by adding extra items
checkoutModel.AddItem(...);

Here are the parameters needed for creating an item:

ParameterDescription
itemNameThe name of the item
assetUrlAn image which represents the item
itemSkuItem's sku
itemAmountItem's Quantity

Example:

// Prepare checkout model
string customerId = "JohnDoe";
string customerEmail = "[email protected]";
int price = 129; // in USD cents 
string currency = "usd";
string offerName = "BestDealPackage"; 
string offerSku = "best_deal_package";
string offerAssetUrl = "https://media-dev.appcharge.com/media/64ad4f25cc1a482bac467ae5/fire-fire-logo-fire-fire-icon-fire-sign-fire-symbol-transparent-background-ai-generative-free-png.png";
string offerDescription = "Coin Pack Bundle";

// Declare a model for getting session token
checkoutModel = new RequestModel(
customerId,
customerEmail,
price,
currency,
offerName,
offerSku,
offerAssetUrl,
offerDescription
);

// Utilize the model by adding extra items
string itemName = "Coins";
string itemAssetUrl = "https://media-dev.appcharge.com/media/product-3.png";
string itemSku = "coins";
int itemAmount = 300;
checkoutModel.AddItem(itemName, itemAssetUrl, itemSku, itemAmount);

Open the checkout using the checkoutModel:

AppchargeManager.OpenCheckoutDirect(checkoutModel);

This function should be called when a user presses a button in your in-game store and once you initialized the checkoutModel.

9. Configure Success Screen and Close Checkout

To use the Appcharge success screen:

  1. Locate the AppChargeConfig file in the folder Assets/Resources/AppCharge.
  2. Turn on the success screen toggle.
  3. Listen to the CheckoutEvents.OnOrderSuccess event, and wait 1.5 seconds for the animation to finish running.
  4. Close the Appcharge SDK using the AppchargeManager.Close function.

To use your own Success screen:

  1. Locate the AppChargeConfig file in the folder Assets/Resources/AppCharge.
  2. Turn off the success screen toggle.
  3. Listen to the CheckoutEvents.OnOrderSuccess event.
  4. Close the Appcharge SDK using the AppchargeManager.Close function.
  5. Show your own success screen. For example:
AppchargeManager.ListenToEvent(CheckoutEvents.OnOrderSuccess, (Dictionary<string, string> args) =>
        {
            Debug.Log("Checkout Success triggered");
            AppchargeManager.Close(); // Close the checkout
        });