Getting started with MRGSAnalytics🔗

MRGSAnalytics integration requires a few simple steps. When this module is included, MRGS will automatically enrich all its events with the appsflyerId parameter, so it will be possible to link data in MRGS with data from AppsFlyer.

Step 1. Import the MRGSAnalytics module🔗

• Add MRGSAnalytics module

  Unity:

  Adding to the project (general instruction)

  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 MRGSAnalytics 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.analytics.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.analytics-<version> package. tgz from the downloaded archive.
  • Import the module: using MRGS;

  iOS:

  Adding to the project (general instruction)

  Swift Package ManagerCocoapodsCarthageManual integration

  Step 1: Add dependencies

  Via Package collection

  • In Xcode select File > Add Packages
  • Select "+" > "Add Swift Package Collection"
  • Insert URL: https://mrgs-nexus.my.games/repository/ios-sdks/MRGSPackageCollection.json
  • Select module MRGSAnalytics from "MRGS Package Collection".
  • Or you can select "MRGS" package from "MRGS Package Collection" (contains all mrgs modules as products) and then select "MRGS/Analytics" product only.

  Individual packages

  • In Xcode select File > Add Packages
  • In the search bar at the top right, paste the URL: https://mrgs-gitea.my.games/mrgs/mrgsanalytics-ios-sdk.git
  • Add a module to your project
  • Or you can paste the url https://mrgs-gitea.my.games/mrgs/ios-sdks.git to include the "MRGS" package which contains all mrgs modules as products and then select only the product" MRGS/Analytics".

  Step 2: Add support for ObjectiveC categories

  • Set the -ObjC flag in the "Other linker Flags" field in the project settings.
  • Import the module in code: @import MRGServiceKit; or @import MRGSAnalytics; or #import <MRGSAnalytics/MRGSAnalytics.h>

  Step 1. Add Sources

  In your podfile, add sources to the top of the file:

  source 'https://github.com/CocoaPods/Specs.git' # For main repo
  source 'https://mrgs-gitea.my.games/mrgs/cocoapods-specs.git'  # For MRGS repo
  

  Step 2: Add dependencies

  Add the latest version of MRGSAnalytics to target:

  To add via subspecs:

  target 'MyProject' do
      pod 'MRGS', '~> 5.0.0', :subspecs => ['Analytics']
  end
  

  To add via individual modules:

  target 'MyProject' do
      pod 'MRGSAnalytics', '~> 5.0.0'
  end
  

  To add all mrgs modules:

  target 'MyProject' do
      pod 'MRGS/AllKits', '~> 5.0.0'
  end
  

  Step 3: Install dependencies

  • Run pod install (or pod install --repo-update if necessary)
  • Import the module in code: @import MRGServiceKit; or @import MRGSAnalytics; or #import <MRGSAnalytics/MRGSAnalytics.h>

  Step 1: Add dependencies

  Add the dependency to your Cartfile:

  binary "https://mrgs-nexus.my.games/repository/ios-sdks/MRGSAnalytics/MRGSAnalytics.json" ~> 5.0.0
  

  Step 2: Install dependencies

  • Run carthage update --use-xcframeworks
  • Add downloaded frameworks to your project (make sure "do not embed" option is enabled)
  • Set the -ObjC flag in the "Other linker Flags" field in the project settings.
  • Import the module in code: @import MRGServiceKit; or @import MRGSAnalytics; or #import <MRGSAnalytics/MRGSAnalytics.h>

  • Download the latest version of the library. Unzip the archive.

  • Add MRGSAnalytics.xcframework from the downloaded archive to your project (Drag the libraries to the "Linked frameworks and Libraries" section) (Also contains MRGSAnalytics.framework for compatibility - fat framework)

  • Set the -ObjC flag in the "Other linker Flags" field in the project settings.

  • Import the module in code: @import MRGSAnalytics; or #import <MRGSAnalytics/MRGSAnalytics.h>
  • Also, you can add the MRGServiceKit.h and module.modulemap files from the archive to your project, or specify the path to them in the project settings in the Build Settings -> Header search paths section. Now, instead of importing each of our frameworks separately, you can only import one header file: @import MRGServiceKit;

  Android:

  Install using GradleManual install

  Add a dependency in build.gradle file:

  dependencies {
      def mrgsVersion = "6.x.x"
  
      implementation "games.my.mrgs:analytics:$mrgsVersion"
  }
  

  Copy the MRGSAnalytics.aar file to the "libs" directory of your project. Add the necessary dependencies to the "build.gradle" file.

  dependencies {
      //...
      implementation(name: 'MRGSAnalytics', ext:'aar')
  
      implementation 'androidx.appcompat:appcompat:1.6.1'
      implementation 'com.appsflyer:af-android-sdk:6.12.1'
      implementation 'com.appsflyer:adrevenue:6.9.1'
      implementation "com.android.installreferrer:installreferrer:2.2"
  }
  

dependencies {
    //... other dependencies
    implementation 'com.appsflyer:oaid:6.1.1'
    implementation files('libs/oaid_sdk_1.0.23.aar')
}

Step 2. Preliminary setup🔗

When initializing MRGS, you must enable AppsFlyer in the external SDK settings, as well as specify the developer key (devKey) and Apple AppID (appId). For Android, you can pass an empty string instead of appId.

using MRGS;

public class MasterController : MonoBehaviour
{
    void Awake()
    {
        // Setting up MRGS parameters
        // ...

        var sdkParams = new MRGSExternalSDKParams
        {
            // ...
            // For Android, you can specify an empty string instead of APPLE_APP_ID
            AppsFlyerParams = new MRGSAppsFlyerParams(APPS_FLYER_DEVKEY, APPLE_APP_ID)
            {
                Debug = false
            }
            // ...
        };

        // Configuring External SDKs and initializing MRGS
        // ...

        MRGService.Instance.Initialize(serviceParams, sdkParams);
    }
}

@import MRGService;

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    //Setting up MRGS parameters
    // ...
    //Setting up external SDKs

    MRGSAppsFlyerParams *appsFlyerParams = [[MRGSAppsFlyerParams alloc] initWithDevKey:<APPS_FLYER_DEVKEY> appleAppId:<APPLE_APP_ID>];

    NSArray *externalParams = @[ ..., appsFlyerParams];
    [MRGService startWithServiceParams:<params> externalSDKParams:externalParams delegate:nil];
}

import games.my.mrgs.MRGSExternalSDKParams;
import games.my.mrgs.MRGSExternalSDKParams.AppsFlyerParams;
import games.my.mrgs.MRGService;
import games.my.mrgs.MRGServiceParams;

public class YourApplicationClass extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        // Setting MRGService
        final MRGServiceParams serviceParams = ...;
        // Setting External SDKs
        final AppsFlyerParams appsFlyerParams = AppsFlyerParams.init("<APPS_FLYER_DEVKEY>");
        appsFlyerParams.setDebuggable(false);

        final MRGSExternalSDKParams externalSDKParams = MRGSExternalSDKParams.newInstance();
        externalSDKParams.appsFlyerParams = appsFlyerParams;

        MRGService.service(context, serviceParams, externalSDKParams);
    }
}

Setting up work with CustomerUserId in AppsFlyer🔗

By default, MRGS will set the CustomerUserId field to the UserId value passed to us via the SetUserId() method.

Delay start until UserId is set🔗

In case you need to delay AppsFlyer start until UserId is set (so that the install event will go away already with the user id), you need to set an additional flag:

appsFlyerParams.WaitForCustomerUserId = true;

appsFlyerParams.waitForCustomerUserId = true;

appsFlyerParams.setWaitForCustomerUserIdEnabled(true);

Set device id (deviceId) to CustomerUserId🔗

In older versions of MRGS, the CustomerUserId field was set to MRGS Device Id by default. To return the old behavior (before 6.0.0-b version), it is enough to set the flag when configuring parameters at the start of MRGS:

appsFlyerParams.UseDeviceIdAsUserId = true;

appsFlyerParams.useDeviceIdAsUserId = true;

appsFlyerParams.setUseDeviceIdAsUserId(true);

Setting your own CustomerUserId🔗

If you want to set your own customerUserID in AppsFlyer use the method:

MRGSAppsFlyer.ForceCustomerUserId("your_customer_user_id");

[MRGSAppsFlyer forceCustomerUserId:@"your_customer_user_id"];

MRGSAppsFlyer#forceCustomerUserId("your_customer_user_id")

Start delay on iOS to wait for ATT🔗

You can also set, when configuring parameters at MRGS startup, the time in seconds that Appsflyer SDK should wait before sending an install / launch event. It is necessary in order to have time to get the user's IDFA on iOS 14+ during the first installation for subsequent attribution. Suitable only for projects that make an IDFA permission request immediately at the start. Only counted on iOS 14+ when no IDFA is received. The default is 0. Read more about this function and the need to use it/configure it in the AppsFlyer official documentation.

appsFlyerParams.WaitForATTUserAuthorization = 10.0f;

appsFlyerParams.waitForATTUserAuthorization = 10.0f;

Step 3. Multi-store Android attribution🔗

Setting up attribution for apps available in multiple Android stores. Choose between combining the data from all stores in a single app dashboard or using a dashboard per store. Learn more

Step 4. Payment tracking🔗

Client🔗

MRGS will send payment information to AppsFlyer, if one of the conditions is met:

• Using MRGSBilling for purchasing.
• Using MRGSMetrics to notify MRGS about payments.
• Using Auto-tracking of payments for iOS.

When sending payment data, MRGS will send the following events and data to AppsFlyer:

If for some reason you need to disable payment tracking, do so at the time of configuring and initializing the MRGS SDK:

sdkParams.AppsFlyerParams.DontForwardReportedPayments = true;

...
appsFlyerParams.dontForwardReportedPayments = YES;

[MRGService startWithServiceParams:<params> externalSDKParams:externalParams delegate:nil];

...
appsFlyerParams.setForwardPaymentsEnabled(false);
externalSDKParams.appsFlyerParams = appsFlyerParams;

MRGService.service(context, serviceParams, externalSDKParams);

Server🔗

By default, MRGS SDK sends purchase data to AppsFlyer. This approach has a significant drawback for subscriptions, when subscriptions are renewed and users do not use the application. So, the accuracy of sending data from the client to AppsFlyer depends on users' activity in the application. MRGS server can monitor renewal subscription and can send this information to AppsFlyer.

To enable this feature:

• Take projectId and devKey from AppsFlyer - learn more.
• Enabled sending data to AppsFlyer in MRGS console: Open your project -> Integration -> AppsFlyer -> Send data to AppsFlyer.
• Add projectId and devKey from AppsFlyer to MRGS console.

If forwarding ad data to Appsflyer is enabled (configured on the mrgs website), then data on advertising revenue sent in unified logs (or collected automatically using the MRGSIronSource module) will be forwarded to AppsFlyer.

Step 5. Tracking events from MRGSMetrics🔗

To track events from MRGSMetrics, just add the setting

...
sdkParams.AppsFlyerParams.ForwardMetrics = true;

...
appsFlyerParams.forwardMetrics = YES;

[MRGService startWithServiceParams:<params> externalSDKParams:externalParams delegate:nil];

...
appsFlyerParams.setForwardMetricsEnabled(true);
externalSDKParams.appsFlyerParams = appsFlyerParams;

MRGService.service(context, serviceParams, externalSDKParams);

Step 6. Integration check🔗

We recommend that you test AppsFlyer using the Integration Tests SDK available at AppsFlyer website. At link you can find a guide on how to conduct integration testing.

Sending events🔗

To work with AppsFlyer, use the object of the class MRGSAppsFlyer:

MRGSAppsFlyer.Instance;

[MRGSAnalytics sharedInstance];

MRGSAnalytics.getInstance().getAppsFlyer();

Using this API, you can send events to AppsFlyer directly. For instance:

MRGSAppsFlyer.Instance.TrackEvent("someEvent", new Dictionary<string, object> { { "unity1", 1 }, { "unity2", "testUserInfo" } });

[[MRGSAnalytics sharedInstance] trackEvent:@"someEvent" eventParams:@{@"level":@"1"}];

Map params = new TreeMap();
params.put("androidParam", "androidValue");

MRGSAnalytics.getInstance().getAppsFlyer().sendEvent("someEvent", params);

When sending any event to AppsFlyer, MRGS will automatically enrich it with mrgs_device_id and mrgs_user_id values.

Get conversion data🔗

To get conversions data, you need to set delegate and implement its methods into your class:

// Conforms to IMRGSAppsFlyerDelegate
MRGSAppsFlyer.Instance.Delegate = this;

// ...
public void OnConversionDataSuccess(Dictionary<string, object> conversionInfo)
{
    Debug.Log("OnConversionDataSuccess: \n" + MRGS.JSON.Json.Serialize(conversionInfo, true));
}
public void OnAppOpenAttribution(Dictionary<string, object> attributionData)
{
    Debug.Log("OnAppOpenAttribution: \n" + MRGS.JSON.Json.Serialize(attributionData, true));
}

[MRGSAnalytics sharedInstance].appsFlyer.delegate = self;
// ...
- (void)onAppOpenAttribution:(NSDictionary *)attributionData {
    NSLog(@"onAppOpenAttribution delegate called with data - %@", attributionData);
}
- (void)onConversionDataSuccess:(NSDictionary *)conversionInfo {
    NSLog(@"onConversionDataSuccess delegate called with data - %@", conversionInfo);
}

MRGSAnalytics.getInstance().getAppsFlyer().setConversionListener(this);//Where "this" is an object that implements the MRGSAppsFlyerConversionListener interface
// ...
@Override
void onConversionDataSuccess(String jsonData) {
    MRGSLog.vp("onConversionDataSuccess " + jsonData);
}

@Override
void onAppOpenAttribution(String jsonData) {
    MRGSLog.vp("onAppOpenAttribution " + jsonData);
}

The structure of the conversionInfo and attributionData dictionaries is described on AppsFlyer website. Dictionary example:

{
    "af_message" = "organic install";
    "af_status" = Organic;
    "install_time" = "2019-12-25 16:00:03.115";
    "is_first_launch" = 0;
}

Get AppsFlyerID🔗

If you need a unique AppsFlyer ID (appsFlyerID), use the following method:

var aID = MRGSAppsFlyer.Instance.GetAppsFlyerId();

NSString* aID = [[MRGSAnalytics sharedInstance].appsFlyer getAppsFlyerId];

String aID = MRGSAnalytics.getInstance().getAppsFlyer().getAppsFlyerId();

Automatic events🔗

MRGS automatically tracks and passes some additional events to AppsFlyer:

User invite attribution🔗

Attribute and record new installs originating from existing users inviting their friends to use your apps. Learn more

Setting OneLink template ID🔗

You need to add it to the AppsFlyer settings when initializing the MRGService SDK, this is the only way to do this.

...
sdkParams.AppsFlyerParams.AppInviteOneLinkID = "your_invite_link_id";

...
appsFlyerParams.appInviteOneLinkID = @"your_invite_link_id";

[MRGService startWithServiceParams:<params> externalSDKParams:externalParams delegate:nil];

...
appsFlyerParams.setAppInviteOneLink("your_invite_link_id");
externalSDKParams.appsFlyerParams = appsFlyerParams;

MRGService.service(context, serviceParams, externalSDKParams);

Creating a link🔗

To create an invitation URL according to various configuration methods, use the following methods from the code below. For more information on the methods, you can use the documentation

// Settings for link generation
var linkParams = new MRGSAppsFlyerLinkOptions
{
    Channel = "your_channel",
    Campaign = "your_campaign",
    ReferrerUID = "your_ref_id",
    ReferrerName = "your_ref_name",
    ReferrerImageURL = "your_ref_image",
    DeeplinkPath = "your_deep_link_path",
    BaseDeeplink = "your_base_deep_link",
    BrandDomain = "your_domain"
};
// If you need to add other custom fields.
linkParams.AddParameterValue("value", "custom_key");

// Link generation
MRGSAppsFlyer.Instance.GenerateUserInviteLink(linkParams, (link, error) =>
{
    Debug.Log("Did receive AppsFlyer invite link - " + link + "; with error - " + error);
});

// AppsFlyer invite link generation
MRGSAppsFlyerLinkOptions* linkParams = [[MRGSAppsFlyerLinkOptions alloc] init];
linkParams.channel = @"facebook";
linkParams.campaign = @"ad_campaign_id";
linkParams.referrerUID = [MRGSAnalytics sharedInstance].appsFlyer.customerUserID;
linkParams.referrerCustomerId = [MRGSAnalytics sharedInstance].appsFlyer.customerUserID;
linkParams.referrerName = @"Ivan Ivanov";
linkParams.referrerImageURL = nil;
linkParams.deeplinkPath = nil;
linkParams.baseDeeplink = nil;
linkParams.brandDomain = @"mrgs.astrum.team";
[linkParams addParameterValue:@"value" forKey:@"custom_key"];  

[[MRGSAnalytics sharedInstance].appsFlyer generateUserInviteLinkWithOptions:linkParams completionHandler:^(NSURL * _Nullable url, NSError * _Nullable linkGenerationError) {
    NSLog(@"Received AppsFlyer invite link - %@,  error - %@", url, linkGenerationError);
}];

import games.my.mrgs.analytics.MRGSAppsFlyerLinkGenerator;

MRGSAppsFlyerLinkGenerator.generateInviteUrl(Context)
        .setChannel("your_channel")
        .setCampaign("your_campaign")
        .setBrandDomain("your_domain")
        // Call the other methods if necessary
        .generateLink(Context, new MRGSAppsFlyerLinkGenerator.ResponseListener() {
            @Override
            public void onResponse(String var1) {
                // handle link here
            }

            @Override
            public void onResponseError(String var1) {
                // handle error here
            }
        });