Unity SDK connection🔗

Minimum requirements🔗

Minimum supported versions: Unity 2018.x, Android 4.4(API: 19), iOS 11.0, and XCode 14.1. MRGService(core) module supports all platforms based on Unity, such as PlayStation, Switch, XBOX, OSX, etc.

Integration🔗

To integrate the MRGS library you need to complete four simple steps:

Step 1. Add the library to the project🔗

Unity Package ManagerManual integration (unitypackage or tgz)

Step 1. Add Sources

To add MRGS to a project via the Unity Package Manager (available from Unity 2018+) simply add a scopedRegistries section to the Packages/manifest.json file by adding the following entry:

{
    "dependencies": {
        ...
    },
    "scopedRegistries": [
            {
                "name": "MRGS",
                "url": "https://mrgs-nexus.my.games/repository/mrgs-uninty-plugins/",
                "scopes": [
                    "games.my.mrgs"
                ]
            }
    ]
}

Alternatively, you can click Edit -> Project Settings -> Package Manager -> '+' in scoped registry section, and fill in the fields according to the data above.

Step 2. Add dependency

Click Window -> Package Manager -> select 'Packages: MyRegistries' from dropdown list, select package MRGService from the list, then click "Install"
Import the module: using MRGS;

Download the latest version of the library. Unzip the archive.
(For unitypackage integration) In Unity, click Assets -> Import Package -> Custom Package, and select the games.my.mrgs.core.unitypackage package from the downloaded archive.
(For tgz integration) In Unity, click Window -> Package Manager -> '+' -> Add package from tarball, and select the games.my.mrgs.core-<version> package. tgz from the downloaded archive.
Import the module: using MRGS;

Play services resolver

MRGS uses the Play services resolver to resolve external dependencies, both for iOS and Android. In case you do not want to use the Play services resolver on iOS / Android, then simply delete it from the project, or turn off the resolver in its settings, then MRGS will automatically determine that the resolver is not used, it will add to the project all the necessary third-party dependencies stored also locally in the package. This rule applies to all MRGS modules. Also, you can manually use define to set the MRGS behavior with the resolver - MRGS_ENABLE_RESOLVER / MRGS_DISABLE_RESOLVER. Also, for each module, you can separately enable this function using defines like MRGS_ENABLE_RESOLVER_<MODULE_NAME_WITHOUT_MRGS> / MRGS_DISABLE_RESOLVER_<MODULE_NAME_WITHOUT_MRGS> ( for example, MRGS_ENABLE_RESOLVER_FIREBASE).

Huawei/AppTouch Store

To support the Huawei/AppTouch Store, add:
1) com.huawei.hms:ads-identifier:3.4.62.300 according to documentation.
2) com.huawei.hms:opendevice:6.11.0.300 according to documentation.

Step 2. Call the initialization method🔗

Call the initialization method MRGService.Instance.Initialize() in the Awake method of the MonoBehaviour class, which is responsible for the main scene in your project. The arguments must be specified MRGS_APP_ID, CLIENT_SECRET.

using MRGS;

public class MasterController : MonoBehaviour
{
    void Awake()
    {
        // MRGService settings
        var serviceParams = new MRGServiceParams(MRGS_APP_ID, CLIENT_SECRET);

        // Requires Platform for Android application
        serviceParams.AndroidExtraOptions.Platform = MRGSPlatformAndroid.Android; // (1)!

        // Start SDK
        MRGService.Instance.Initialize(serviceParams);
    }
}

This is required only when building for Android. Available platforms: Amazon, Android, Huawei, Samsung, and FacebookCloud

Android MRGSPlatform

When initializing MRGService under Android, you need to pass MRGSPlatform (that is, the store where you plan to upload the build).

MRGS_APP_ID and CLIENT_SECRET

MRGS_APP_ID - Application ID on the MRGS website. CLIENT_SECRET - Client Key. You can get them from the MRGS website, in the settings section of your application Important! Do not forget that these parameters are different for Android and iOS builds. Use the correct initialization keys app_settings

Attention! Calling any methods (except the GDPR) before calling the SDK start method can lead to undefined MRGS behavior. Be careful not to start working with MRGS before calling the initialization method!

User tracking request on iOS 14+

In case you want to show a popup of a request for tracking permissions (getting IDFA) in iOS 14, you can use our display methods. Usually IDFA is required for ad tracking, you can read more on the link above

Step 3 (Optional). Add account login tracking🔗

If your application uses a player identifier (USER_ID), it must be passed to MRGS using the method:

MRGSUsers.Instance.SetUserId(USER_ID);

Step 4. Add payment tracking🔗

After the payment is made, it is necessary to report data about it to MRGS.

iOS

By default, MRGS on iOS will automatically collect all payment data using autotracking, no further action is required.

If you don't want to use autotracking, then you need to turn off automatic payment tracking (serviceParams.IOSExtraOptions.AutomaticPaymentTracking = false;) and use the method for direct transfer of payment data described below (not recommended approach).

To send payment data, you can use the following method:

MRGSMetrics.Instance.AddPurchase(MRGSPurchaseEvent);

// Or if you're using Unity IAP:
MRGSMetrics.Instance.AddPurchase(UnityEngine.Purchasing.Product);

In case you are using Unity IAP and if define UNITY_PURCHASING for some reason is not set in your project, you can force enable the visibility of the method using define MRGS_FORCE_UNITY_IAP

Examples of sending payment data on different platforms:

Example for Android (GooglePlay)

skuDetails - product information in JSON format. You can get it by calling the getSkuDetails method.
purchaseData - this is the INAPP_PURCHASE_DATA field received from Google reply after purchase getBuyIntent method.
dataSignature - this is the INAPP_PURCHASE_SIGNATURE field received from Google reply after purchase getBuyIntent method.

var purchaseEvent = MRGSPurchaseEvent.Google(skuDetails, purchaseData, dataSignature);
MRGSMetrics.Instance.AddPurchase(purchaseEvent);

Example for Huawei/AppTouch

inAppPurchaseDataJson - purchase information in JSON format. You can get it by calling the com.huawei.hms.iap.entity.PurchaseResultInfo#getInAppPurchaseData() method.
inAppSignature - encrypted payment information. You can get it by calling the com.huawei.hms.iap.entity.PurchaseResultInfo#getInAppDataSignature() method.

var purchaseEvent = MRGSPurchaseEvent.Huawei(inAppPurchaseDataJson, inAppSignature);
MRGSMetrics.Instance.AddPurchase(purchaseEvent);

Example for Samsung

productVoJson - product information in JSON format. You can get it by calling the com.samsung.android.sdk.iap.lib.vo.ProductVo#getJsonString() method.
purchaseVoJson - purchase information in JSON format. You can get it by calling the com.samsung.android.sdk.iap.lib.vo.PurchaseVo#getJsonString() method.

var purchaseEvent = MRGSPurchaseEvent.Samsung(productVoJson, purchaseVoJson);
MRGSMetrics.Instance.AddPurchase(purchaseEvent);

Example for Amazon

productJson - product information in JSON format. You can get it by calling the com.amazon.device.iap.model.Product#toJSON() method.
receiptJson - purchase information in JSON format. You can get it by calling the com.amazon.device.iap.model.Receipt#toJSON() method.
userDataJson - buyer information in JSON format. You can get it by calling the com.amazon.device.iap.model.UserData#toJSON() method.

var purchaseEvent = MRGSPurchaseEvent.Amazon(productJson, receiptJson, userDataJson);
MRGSMetrics.Instance.AddPurchase(purchaseEvent);

Example for iOS

product - product information.
transactionIdentifier - transaction identifier.
transactionReceipt - transaction receipt in old base64 format (not applicationReceipt).

// Setting SDK params
serviceParams.IOSExtraOptions.AutomaticPaymentTracking = false;

// Sending payment
var product = MRGSPurchaseEvent.Product.Builder("games.my.mrgs.weapon6")
        .WithLocalizedTitle("Great gold weapon")
        .WithLocalizedDescription("Destroy anyone with this gun. Limited edition!")
        .WithPrice("15")
        .WithPriceCurrency("USD")
        .Build();
var transactionIdentifier = "1000000353116913";
var transactionReceipt = "MIIVSwYJKoZIhvcNAQcCoIIVPDCCFTgCAQExCzAJBgUrDg.........85+V19vrPYvnHcHh8yZEpRhtmlRmlWN+AWhJmYjuu4SGfIzg3oo416EWIYV8tke3t8pmHGClmoO7q+478RDbnmuBROz/1NQdlevyeyFkae/VCDRQ==";

var purchaseEvent = MRGSPurchaseEvent.IOS(product, transactionIdentifier, transactionReceipt);
MRGSMetrics.Instance.AddPurchase(purchaseEvent);

Example for Standalone platform (Windows, OSX, PlayStation, Xbox, Switch, etc.)

var product = MRGSPurchaseEvent.Product.Builder("weapon_34")
        .WithLocalizedTitle("Great gold weapon")
        .WithLocalizedDescription("Limited edition")
        .WithPrice("1234.5")
        .WithPriceCurrency("USD")
        .Build();
var transactionIdentifier = "123456789";
var purchaseEvent = MRGSPurchaseEvent.Standalone(transactionIdentifier, product);
MRGSMetrics.Instance.AddPurchase(purchaseEvent);

Example for third-party payment systems

Since MRGS 6.1.0 version, you can send payment information for any third-party payment systems to MRGS. Such payments will never be validated by MRGS, and they will be recorded in the database as is:

var transactionId = "1234-5678-000-ABCD";
const string productId = "com.your.product.custom10";
const float price = 12f;
const string currency = "EUR";
var revenue = new MRGSPurchaseEvent.Revenue(transactionId, productId, price, currency)
{
    Title = "Custom Product",
    Description = "Custom product need for test",
};

var purchaseEvent = MRGSPurchaseEvent.CustomEvent(revenue);
MRGSMetrics.Instance.AddPurchase(purchaseEvent);

Important

Payment tracking is necessary if you do not use the MRGSBank module.
Make sure that on the site https://mrgs.astrum.team, in the settings of your application, the fields with keys for validating payments are filled in and the setting "Only validation of payments (without processing)" is enabled.
MRGS will automatically send information about purchases to all the configured SDKs: AppsFlyer(only iOS, Android, Huawei/AppTouch and Samsung purchases), Firebase(only iOS and Android purchases), MyTracker(only iOS and Android purchases) if the corresponding modules are enabled
Autotracking on iOS is automatically disabled when using the MRGSBank module.

Integration check🔗

After completing the MRGS integration, we recommend that you verify that the library is working correctly. To learn how to perform this procedure, see Integration checks and troubleshooting section.

SDK Update🔗

When updating the SDK via the Unity Package Manager, it is enough to update the SDK in the UPM interface, and in case you have integrated the .unitypackage solution, we recommend that you completely delete the Assets/MRGS/<games.my.mrgs.<module_name> folder, after which import an already updated version of the SDK.

Last update: 2025-01-21
Created: 2020-01-20