Laya Integration Guidelines | MiniGame Developer Center

Revision History

Date	Version
2024/2/26	1.0.0
2024/3/22	1.0.1
2024/7/12	1.0.2
2024/10/23	1.0.3

Integration Process(Based on Laya 2.x)

Place the two SDK configuration files we provided into the project's bin directory. The two files are minigame-config.json, minigame.json 。
Load the minigame.js file in index.html.

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

In Main.ts, initialize and start the minigame SDK. Since initialization is asynchronous, it is necessary to wait until the initialization is successful before starting the SDK.

onConfigLoaded(): void {
    // @ts-ignore
    if (typeof minigame !== 'undefined') {
      let that = this;
      //Initialize minigame sdk
      // @ts-ignore
      minigame.initializeAsync()
        .then(function () {
            console.log("FB initializeAsync");
            that.onLoadRes();
        });
}

// Resource loading
private onLoadRes() {
	...
	// Start the SDK after resources are loaded
	this.startMiniGameSDK();
}

// Start minigame sdk
private startMiniGameSDK() {
	// @ts-ignore
	if (typeof minigame !== 'undefined') {
	  //@ts-ignore
	  minigame.setLoadingProgress(100);
	  //@ts-ignore
	  minigame.startGameAsync()
	  .then(function () {
		//Load the scene specified by the IDE, assuming the first scene name is startScene
		GameConfig.startScene && Laya.Scene.open(GameConfig.startScene);
	  })
	  .catch(function (e) {
		  console.info("startGameAsync error: " + e);
	  });      
	}
}

Once the SDK is started, you can call the advertising-related interfaces.After successful integration, you can call the advertising-related interfaces, and after compiling with Laya, you can run and see the effect directly.

Note:It is essential to ensure that the calls to the advertising interfaces must be made after the successful return of startGameAsync.

When the game finishes loading and enters the main scene, call setGameReadyAsync when the main scene is initialized.
```
minigame.setGameReadyAsync();
```

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.

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://sdk0.minigame.vip/js/1.0/minigame-debug-sdk.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>

Parameters: None

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): void
//example usage:
// 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:

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
        });
});

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 shareable image, encoded in base64
   * 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.If not specified, all available share destinations will be displayed.
   */
  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. */
    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;
}

Data Storage (Required)

Data Saving

setDataAsync (data: Object): Promise<void>

minigame.player
  .setDataAsync({
    achievements: ['medal1', 'medal2', 'medal3'],
    currentLife: 300,
  })
  .then(function() {
    console.log('data is set');
  });

Data Retrieval

minigame.player
  .getDataAsync(['achievements', 'currentLife'])
  .then(function(data) {
     console.log('data is loaded');
     var achievements = data['achievements'];
     var currentLife = data['currentLife'];
  });

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.
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

Revision History

Integration Process(Based on Laya 2.x)

Interface

Advertising related interface

Game Analytics (Integrate only if needed)

In-App Purchases (Integrate only if needed)

In-App purchase interface

Type definition

Add desktop shortcut (Pinned) (Integrate only if needed)

Sharing (Integrate only if needed)

Language

Invitation

Data Storage (Required)

Data Saving

Data Retrieval

Local testing environment

Simulating Online Environment