Unity Integration Guidelines | MiniGame Developer Center

Revision History

Date	Version
2024/2/26	1.0.0
2024/3/22	1.0.1
2024/5/11	1.0.2
2024/10/23	1.0.3

Integration Process(Based on Unity 2020)

1. Add the minigame release template

Unity provides two default templates (Default and Minimal), both located in the Unity installation directory.

The SDK uses the Default template because this template has more complete functionality.Copy the Default directory to the project's Assets/WebGLTemplates/<Your Template directory>.Assuming the template directory is named minigameDefault, then the project's Assets directory would look something like this:

When packaging, an additional option named minigameDefault will appear in the WebGL Template. Select minigameDefault when packaging.

2. Remove the warning when running on mobile devices

In the minigameDefault template project's entry file index.html, comment out the following code, otherwise Unity will display a warning when running on a mobile device.

And change it to the following:

// Change to 'unity-mobile' to display it in full screen
container.className = "unity-mobile";
config.devicePixelRatio = 1;

You can also directly modify the class of the 'unity-container':

<div id="unity-container" class="unity-mobile">
...
</div>

The package built by Unity usually has a scrollbar on the right side, as shown below

You need to add css style to the body to hide the scrollbar

<body style="overflow: hidden;">

3. Add SDK link

Add the SDK link in the head tag of index.html:

<script src="https://sdk.minigame.vip/js/1.1/minigame.js"></script>

4.Add SDK startup code

In the index.html file, encapsulate the Unity startup method as startUnity，At the location of the progress bar, call the progress display interface with minigame.setLoadingProgress(100 * progress);, Assign the unityInstance to a global object.
window.unityInstance = unityInstance; ，for subsequent interactions with the SDK, and finally, to launch the SDK: minigame.startGameAsync()

function startUnity(){
  var script = document.createElement("script");
  script.src = loaderUrl;
  script.onload = () => {
    createUnityInstance(canvas, config, (progress) => {
      progressBarFull.style.width = 100 * progress + "%";
      minigame.setLoadingProgress(100 * progress);
    }).then((unityInstance) => {
      loadingBar.style.display = "none";
      fullscreenButton.onclick = () => {
        unityInstance.SetFullscreen(1);              
      };
      window.unityInstance = unityInstance;
	  // Delay for 2 seconds to skip the logo animation
	  setTimeout(() => {
		minigame.startGameAsync();
	  }, 2000);
    }).catch((message) => {
      alert(message);
    });
  };
  document.body.appendChild(script);
}

Call the initialization method minigame.initializeAsync，and after the initialization is successful, call startUnity。

minigame.initializeAsync()
  .then(function () {
    console.info("minigame initializeAsync..");
	// Start the game
	startUnity();
  })
  .catch(function (e) {
	cc.error("minigame-sdk init error: ", e); 
  })

5. Interaction between Unity and SDK

Unity provides files with the .jslib extension for interaction between Unity and JavaScript.Those who are not familiar can refer to the official link: https://docs.unity3d.com/cn/2018.4/Manual/webgl-interactingwithbrowserscripting.html

js calls Unity:

Here, it is assumed that the .jslib file is named JS.jslib, Place theJS.jslib file in the "Plugins" subfolder within the Assets folder. Add the advertisement interface calls to this file, and use unityInstance.SendMessage to send messages from the JavaScript layer to the Unity layer, assuming the object with the advertisement code in the scene is named ScriptControl。

mergeInto(LibraryManager.library, {
	// Show interstitial ad
	showInterstitial: function() {
		if (typeof MiniGameAds === "undefined") {
		  console.error("MiniGameAds is undefined");
		  return;
		}

		MiniGameAds.showInterstitial()
		.then(function() {
			// Successfully shown, call showInterstitialCallback, return success result 1
			unityInstance.SendMessage("ScriptControl", "showInterstitialCallback", 1);
		}).catch(function(e) {
		        // Successfully shown, call showInterstitialCallback, return failure result 0
			unityInstance.SendMessage("ScriptControl", "showInterstitialCallback", 0);
		});
	},

  // Show rewarded video
	showRewardedVideo: function() {
		if (typeof MiniGameAds === "undefined") {
		  console.error("MiniGameAds is undefined");
		  return;
		}

		MiniGameAds.showRewardedVideo()
        .then(function() {
      			// Successfully shown, call showRewardedCallback, pass success result 1
            unityInstance.SendMessage("ScriptControl", "showReWardedCallback", 1);
        }).catch(function(e) {
      			// Successfully shown, call showRewardedCallback, pass failure result 0
            unityInstance.SendMessage("ScriptControl", "showReWardedCallback", 0);
        });
	},

  // Show banner
	showBanner: function() {
		if (typeof MiniGameAds === "undefined") {
		  console.error("MiniGameAds is undefined");
		  return;
		}

		MiniGameAds.showBanner().then(function() {
			      // Successfully shown, call showBannerCallback, pass success result 1
            unityInstance.SendMessage("ScriptControl", "showBannerCallback", 1);
        }).catch(function(e){
       			// Successfully shown, call showBannerCallback, pass failure result 0
            unityInstance.SendMessage("ScriptControl", "showBannerCallback", 0);
        });
	},

  // Hide banner
	hideBanner: function() {
		if (typeof MiniGameAds === "undefined") {
		  console.error("MiniGameAds is undefined");
		  return;
		}

 		MiniGameAds.hideBanner().then(function() {
      			// Successfully shown, call hideBannerCallback, pass success result 1
            unityInstance.SendMessage("ScriptControl", "hideBannerCallback", 1);
        }).catch(function() {
         		// Successfully shown, call hideBannerCallback, pass failure result 0
            unityInstance.SendMessage("ScriptControl", "hideBannerCallback", 0);
        });
	}
});

Unity calls js

public class AdsControl : MonoBehaviour {
  // Declare import of external methods
  [DllImport("__Internal")]
  private static extern void showInterstitial();

  [DllImport("__Internal")]
  private static extern void showRewardedVideo();

  [DllImport("__Internal")]
  private static extern void showBanner();

  [DllImport("__Internal")]
  private static extern void hideBanner();                    
	
  // Rewarded video callback, handle reward distribution
  public void showReWardedCallback(int isSuccess) {
    Debug.Log("show reward: " + (isSuccess == 1 ? "success" : "failed"));
  }

  // Interstitial ad callback, no need to handle since no reward is given 
  public void showInterstitialCallback(int isSuccess) {
    Debug.Log("show Interstitial: " + (isSuccess == 1 ? "success" : "failed"));
  }

  // banner ad callback, no need to handle since no reward is given
  public void showBannerCallback(int isSuccess) {
    Debug.Log("show banner: " + (isSuccess == 1 ? "success" : "failed"));
  }

  // banner ad hide callback, no need to handle since no reward is given
  public void hideBannerCallback(int isSuccess) {
    Debug.Log("hide banner: " + (isSuccess == 1 ? "success" : "failed"));
  }

  // Show interstitial ad, call the showInterstitial declared in JS.jslib showInterstitial
  public void showInterstitialAd()
  {
    showInterstitial();
  }

  // Show interstitial ad, call the showRewardedVideo declared in JS.jslib showRewardedVideo
  public void ShowRewardedVideoAd()
  {
    showRewardedVideo();
  }

  // Show interstitial ad, call the showBanner declared in JS.jslib
  public void showBannerAd()
  {
    showBanner();
  }

  // Show interstitial ad, call the hideBanner declared in JS.jslib
  public void hideBannerAd()
  {
    hideBanner();
  }
}

6. WebGL packaging

When packaging WebGL, resource compression is enabled by default. Since many platform servers do not have the compressed format file headers enabled, there are two choices:

1.Disable resource compression: This will result in a larger game package size.

2.Enable decompression fallback: By default, this is disabled. Enabling it will increase the size of the loader and reduce the efficiency of the file loading scheme, which will increase the game loading time.

The specific choice depends on the actual situation of the game project:

For games on the MiniGame platform:Use Option 2.
For games on the Facebook platform:Use Option 1.

Interface

It is recommended to use the advertising interface (MiniGameAds) provided by the MiniGame SDK for advertising functionality. Game developers who are familiar with the FBIG interface can also use the FBIG compatible advertising interface directly. It is recommended to use MiniGameAds.

MiniGameAds mainly has 5 interfaces:

showInterstitial(): Promise<void>

Purpose:To display interstitial ads
Example:

// @ts-ignore
MiniGameAds.showInterstitial().then(()=>{
	console.info("====> show interstitial success");
}).catch(e => {
	console.error("====> show interstitial error: " + e.message);
});

Note:Since interstitial ads are set to default to a 30-second delay before they can be played for the first time, and then have a 40-second interval between subsequent plays, if the content provider (CP) finds the waiting time too long during testing, they can reduce the fb_ad_delay_for_first_interstitial and fb_interstitial_refresh_interval fields in the minigame.json file.

showRewardedVideo()：Promise<void>

Purpose:To display a rewarded video ad
Example:

// @ts-ignore
MiniGameAds.showRewardedVideo().then(()=>{
	console.info("====> show RewardedVideo success");
}).catch(e => {
	console.error("====> show RewardedVideo error: " + e.message);
});

isAdRadical(): boolean

Purpose:Radical ad version switch
Return:true for radical version of rewarded ads, which requires displaying the radical version UI, false for the regular version of rewarded ads, which requires displaying the regular version UI.
Radical version:Includes ad strategies that involve accidental clicks and deceptive practices, such as:

Default check: Automatically selects the option to watch rewarded videos for double rewards, with the selection text being too small to notice.
Delay prompt: Omits the option to not watch the rewarded ad, leading users to believe there is only one choice.

Regular Version:Does not include the ad strategies of accidental clicks and deceptive practices found in the radical version.

Note: If there are radical rewarded ads in the game, two sets of treatments are needed: two sets of handling are required: one follows the original radical version processing, and another follows the regular version processing.
By adding the field isAdRadical in the minigame.json, you can control the return value of isAdRadical().
"isAdRadical()": If true, then isAdRadical()===true, "isAdRadical()": If false, then isAdRadical()===false

Example:

const isAdRadical = MiniGameAds.isAdRadical();
// Determine whether to display the radical version UI or the regular version UI based on isAdRadical.

The specific configuration in minigame.json is as follows:

{
  "platform": "minigame",
  "sdk": "https://sdk.minigame.vip/js/1.0/minigame-sdk.debug.js",
  "instance": "FBInstant",
  "gameName": "minigame",
  "features": {
    "ads": {
      "enabled": false, // Ad switch
      "isBannerEnabled": true, // banner switch
      "isTest": true, // Whether it is a local ad testing environment
      "isAdRadical": true, // Whether it is an radical version of rewarded ads
      "config": {
        "interstitial": "4864743603539728_5070034729677280",
        "banner": "4864743603539728_5082905605056859",
        "rewarded_video": "4864743603539728_5070034119677341",
        "rewarded_interstitial": "4864743603539728_5070034119677341"
      },
      "options": {
        "fb_max_ad_instance": 3,
        "fb_init_ad_count": 3,

        "fb_banner_refresh_interval": 40,
        "fb_interstitial_refresh_interval": 40,
        "fb_rewarded_video_refresh_interval": 0,

        "fb_max_banner_error": 1,
        "fb_max_interstitial_error": 3,
        "fb_max_rewarded_video_error": 3,

        "fb_auto_load_on_play": true,
        "fb_auto_reload_delay": 1,

        "fb_ad_delay_for_first_banner": 0,
        "fb_ad_delay_for_first_interstitial": 30,
        "fb_ad_delay_for_first_rewarded_video": 0
      }
    },
    "leaderboard": {
      "enabled": true
    },
    "ga": {
		"enabled": true,
		"isDefault": true,
		"config": {
			"gid": "UA-226110216-21"
		}
     }
  }
}

showBanner(): Promise<void>

Purpose:To display banner ads
Example:

// @ts-ignore
MiniGameAds.showBanner().then(()=>{
	console.info("====> show banner success");
}).catch(e => {
	console.error("====> show banner error: " + e.message);
});

hideBanner(): Promise<void>

Purpose:Hide banner ads
Example:

// @ts-ignore
MiniGameAds.hideBanner().then(()=>{
    console.info("====> hide banner success");
}).catch(e => {
    console.error("====> hide banner error: " + e.message);
});

Game Analytics (Integrate only if needed)

onGameEvent

/**
  * @param eventName Event Name
  * @param label  Event label
  */
public onGameEvent (eventName: string, label: string)

Usage example:

// Account login
// @ts-ignore
MiniGameAnalytics.onGameEvent("login", "custom label");

In-App Purchases (Integrate only if needed)

In-App purchase interface

onReady(callBack: Function): void
Set up a callback that will be triggered when the payment is available. onReady is generally called after entering the game. You can handle the operation of processing pending orders within the callback. Examples:

Examples:

minigame.payments.onReady(function () {
    // First, retrieve unconsumed orders
    minigame.payments.getPurchasesAsync().then(function(purchases) {
      console.log(purchases);
      // Iterate through the orders
      purchases.forEach((purchase) => {
          // Consume the order
           minigame.payments.consumePurchaseAsync(purchase.purchaseToken)
                .then(function () {
                  // Successfully consumed
                  // The game sends rewards to the player
                });
          })
    });
});

getCatalogAsync(): Promise<Product[]>
Retrieve the game's product catalog

Examples:

minigame.payments.getCatalogAsync().then(function (catalog) {   
  console.log(catalog); // [{productID: '12345', ...}, ...]  
});

purchaseAsync(purchaseConfig: PurchaseConfig): Promise<Purchase>
Start the purchase process for a specific product. The productID will be provided when integrating

Examples:

minigame.payments.purchaseAsync(
{  productID: '12345',  
   developerPayload: 'foobar'
}).then(function (purchase) {
  console.log(purchase);// {productID: '12345', purchaseToken: '54321', developerPayload: 'foobar', ...}
});

getPurchasesAsync(): Promise<Purchase[]>
Retrieve all purchased products that the player has not yet consumed

Examples:

minigame.payments.getPurchasesAsync().then(function (purchases) {
  console.log(purchase);
  // [{productID: '12345', ...}, ...]
});

consumePurchaseAsync(purchaseToken: string): Promise<void>
Consume a specific purchased product that the player currently owns

Examples:

minigame.payments.consumePurchaseAsync('54321').then(function () {
  // Successfully consumed
  // The game sends rewards to the player
});

Note: After a successful payment with purchaseAsync, you must immediately call the consumption interface to issue rewards. For example:

minigame.payments.purchaseAsync({
  productID: '12345',
  developerPayload: 'foobar',
}).then(function (purchase) {         
    minigame.payments.consumePurchaseAsync(purchase.purchaseToken)
      .then(function () {
          // Successfully consumed
          // The game sends rewards to the player
        });
});

2.Type definition

Payment parameters:

export interface PurchaseConfig {
  /**
   * product ID
   */
  productID: string;
  /**
   * Optional parameter, content specified by the developer, which will be included in the returned purchase signature request.
   */
  developerPayload?: string;
}

Product information:

export interface Product {
  /**
   * The title of the product
   */
  title: string;
  /**
   * The game-specified ID of the product
   */
  productID: string;
  /**
   * A description of the product
   */
  description?: string;
  /**
   * The link to the product's related image
   */
  imageURI?: string;
  /**
   * The price of the product
   */
  price: string;
  /**
   * The currency code of the product's price, string type
   */
  priceCurrencyCode: string;
  /**
   * The price amount of the product, numeric type
   */
  priceAmount: number;
}

Payment response:

export interface Purchase {
  /**
   * Optional parameter, content specified by the developer, which will be included in the returned purchase signature request.
   */
  developerPayload?: string;
  /**
   * The current status of the purchase, such as "charged" or "refunded"
   */
  paymentActionType: string;
  /**
   * The identifier for the purchase transaction
   */
  paymentID: string;
  /**
   * product ID
   */
  productID: string;
  /**
   * The local currency amount and currency associated with the purchase item
   */
  purchasePrice: string;
  /**
   * The Unix timestamp when the purchase occurred
   */
  purchaseTime: string;
  /**
   * A token representing the purchase made by the consumer
   */
  purchaseToken: string;
  /**
   * The server signature for the purchase request
   */
  signedRequest: string;
}

Add Desktop Shortcut (Pinned) (Integrate only if needed)

canCreateShortcutAsync(): Promise<boolean>;
Check if you can prepare to create a shortcut
createShortcutAsync( ): Promise<void>;
Create shortcut

Examples：

minigame.canCreateShortcutAsync()
  .then(function(canCreateShortcut) {
  	// If it's possible to create
    if (canCreateShortcut) {
      // Attempt to create the shortcut
      minigame.createShortcutAsync()
        .then(function() {
          // Shortcut created
        	console.info("call createShortcutAsync done");
        })
        .catch(function(error) {
          // Shortcut not created
	        console.info("call createShortcutAsync fail: ", error);
        });
    }
  })
  .catch(function(error) {
  	console.info("canCreateShortcut fail: ", error);
  });

Note:You must first determine if you are ready before creating a shortcut.

shareAsync(payload: SharePayload): Promise<void>

Examples：

minigame.shareAsync({
  image: base64Picture,
  text: 'X is asking for your help!',
  data: { myReplayData: '...' },
  switchContext: false,
}).then(function() {
  // success to share, continue with the game.
})
.catch(function(error) {
  // share fail
});

Parameter definition:

interface SharePayload {
  /**
   * Indicates the intent of the share. In version 7.1, this has been removed and is compatible with the old version.
   * "INVITE" | "REQUEST" | "CHALLENGE" | "SHARE"
   */
  intent?: string;
  /**
   * A base64 encoded image to be shared.
   */
  image: string;

  /*
   * gif or video
   */
  media?: MediaParams;

  /**
   * A text message to be shared.
   */
  text: string;
  /**
   * Data attached to the share.
   * All games started from this shared activity can obtain this data through the FBInstant.getEntryPointData() method.
   *  A blob of data to attach to the share.
   */
  data?: Object;
  /**
   * An optional array to set the share destination in the sharing dialog.
   */
  shareDestination?: string[],
  /**
   * A flag indicating whether to switch the user to a new context created during sharing
   */
  switchContext?: boolean,
}

Language

getLocale(): string;

const lang = minigame.getLocale(); //  Assuming the current environment is American English, it returns en_US"
// Check if the current language is English	
if (lang.includes("en")){
	console.info("current language is en");
}
// Or
if (lang.substr(0, 2) === "en"){
	console.info("current language is en");
}

Invitation

inviteAsync(payload: InvitePayload ): Promise<void>;

minigame.inviteAsync({
  image: base64Picture,
  text: {
    default: 'X just invaded Y\'s village!',
    localizations: {
      ar_AR: 'X \u0641\u0642\u0637 \u063A\u0632\u062A ' +
        '\u0642\u0631\u064A\u0629 Y!',
      en_US: 'X just invaded Y\'s village!',
      es_LA: '\u00A1X acaba de invadir el pueblo de Y!'
    }
  },
  data: { myReplayData: '...' }
}).then(function() {
  // continue with the game.
}).catch(function(error){
	console.error("invite error: ", error);
})

Parameter definition:

interface InvitePayload {
  /* A base64 encoded image for sharing.*/
  image: string;
  /* A text message, or an object containing a default text as the 'default' value and another object mapping language region keys to translated 'localizations' values.*/
  text: string | LocalizableContent;
  /*
   * Optional call-to-action button text. By default, we will use the localized "Play" as the button text. If you want to provide your own localized version of the call-to-action, pass an object with the default cta as the 'default' value, and map language region keys to translations as 'localizations' values.
   */
  cta?: string | LocalizableContent;
  /* Data to be attached to the share. All conversations started from the share can access this data block via FBInstant.getEntryPointData().*/
  data?: Object;
  /*  A set of suggested filters to apply. Multiple filters can be applied. If no results are returned when applying filters, a result without filters will be generated*/
  filters?: Array<InviteSection>;
  /*
   * An array of sections included in the dialog box. Each section can be assigned a maximum number of results to return (up to 10).If the maximum value is not included, the default maximum value will be applied. Sections will be included in the order they are listed in the array. The last section will include a larger maximum number of results; if maxResults is provided, it will be ignored. If this array is empty, the default section will be used.
   */
  sections?: Array<InviteSection>;
  /* An optional title displayed at the top of the invitation dialog box, instead of a generic title. This parameter is not sent as part of the message but is displayed only in the dialog title. The title can be a string or an object with the default text as the 'default' value, and mapping language region keys to translations as 'localizations' values. */
  dialogTitle?: string | LocalizableContent;
}

interface InviteSectionType {
    /** This includes group context, such as the context from the group chat. */
    GROUPS: string;
    /** This includes individual users, such as friends or 1:1 threads. */
    USERS: string;
}

interface LocalizationsDict {
    [key: string]: string;
}

/** Represents a string with a default value and a localized value that can be relied upon. */
interface LocalizableContent {
    /** The default value to use when the viewer's region setting does not match an object key. This is the value to use when there is no localization match. */
    default: string;
    /**  Specifies the string to use for each region setting. A complete list of supported region values.
 */
    localizations: LocalizationsDict;
}

interface InviteSection {
    /** The type of section to be included in the informAsync dialog box. */
    sectionType: InviteSectionType;
    /** The maximum number of results that can be included in this section. This value should not exceed 10. The last section will ignore this value, and will include as many results as possible. If not included, the default maximum number of results for this section type will be used. */
    maxResults: number;
}

Local Testing Environment

To start a web server at the root directory of the game, there are many ways to create a web server, such as modules like http-server in node.js, Serve, and SimpleHTTPServer in python, etc. The specific library to use is up to the developer's decision.

Here is an example using Node.js's http-server:

Set isTest to true in minigame.json.
2.Start the web server at the root directory by executing the command: http-server -o -c -l, which will automatically open a browser and navigate to http://127.0.0.1:8080/. You can then proceed to test the ads directly.

Simulating Online Environment

Steps:

Open https://minigamecloud.com/testgame .
Set isTest to false in minigame.json.
Place the local game link after integrating the SDK into the address bar of the page.
After clicking "Start Testing," you can simulate the online environment for testing.

------------------------------------------------------ END ---------------------------------------------------------------------------

Outline