Skip to content

Begin working with cross-promotion (Piligrim)🔗

To integrate cross-promotion (Piligrim) you need to make a few simple steps.

Step 1. Import the cross-promotion module🔗

  • Add MRGSAdvertising module

    Unity:

    Adding to the project (general instruction)

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

    iOS:

    Adding to the project (general instruction)

    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 MRGSAdvertising from "MRGS Package Collection".
    • Or you can select "MRGS" package from "MRGS Package Collection" (contains all mrgs modules as products) and then select "MRGS/Advertising" 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/mrgsadvertising-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/Advertising".

    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 MRGSAdvertising; or #import <MRGSAdvertising/MRGSAdvertising.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 MRGSAdvertising to target:

    To add via subspecs:

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

    To add via individual modules:

    target 'MyProject' do
        pod 'MRGSAdvertising', '~> 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 MRGSAdvertising; or #import <MRGSAdvertising/MRGSAdvertising.h>

    Step 1: Add dependencies

    Add the dependency to your Cartfile:

    binary "https://mrgs-nexus.my.games/repository/ios-sdks/MRGSAdvertising/MRGSAdvertising.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 MRGSAdvertising; or #import <MRGSAdvertising/MRGSAdvertising.h>
    • Download the latest version of the library. Unzip the archive.
    • Add MRGSAdvertising.xcframework from the downloaded archive to your project (Drag the libraries to the "Linked frameworks and Libraries" section) (Also contains MRGSAdvertising.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 MRGSAdvertising; or #import <MRGSAdvertising/MRGSAdvertising.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:

    Add a dependency in build.gradle file:

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

    Copy the MRGSAdvertising.aar file into the libs directory of your project. Add the necessary dependencies into the build.gradle file.

    dependencies {
        //...
        implementation(name: 'MRGSAdvertising', ext:'aar')
    
        implementation 'androidx.appcompat:appcompat:1.6.1'
        implementation 'androidx.recyclerview:recyclerview:1.2.1'
        implementation 'androidx.localbroadcastmanager:localbroadcastmanager:1.0.0'
        implementation 'androidx.vectordrawable:vectordrawable:1.1.0'
    }
    

User tracking request on iOS 14+

For more accurate tracking of ads, conversions, etc. IDFA is required. On iOS 14+, you must request this permission from the user. If you want to show a popup of a request for tracking permissions (getting IDFA) in iOS 14, you can use our display methods.

Step 2. Create an advertising object🔗

First, you need to create an object for the advertising work. It is possible to work with static ads, or with video ads and playable ads.

To initialize the object use the following methods:

// Static Ad
MRGSAdvertising staticAD = MRGSAdvertising.GetBanner();

// Vedeo or playable ad
MRGSAdvertising videoAD = MRGSAdvertising.GetVideo();
//Static ad
MRGSAdvertising* staticAD = [[MRGSAdvertisingManager sharedInstance] getAdvertising]; //Take ads from the general massive

//Video ad or playable ad
MRGSAdvertising* videoAD = [[MRGSAdvertisingManager sharedInstance] createAdvertising:YES]; //YES determines, that this object will receive only video content and playable ads
//Static ad
MRGSAdvert staticAD = MRGSAdvertisingFactory.getMRGSAdvertising();

//Video ad or playable ad
MRGSAdvert videoAD = MRGSAdvertisingFactory.createMRGSAdvertising(true); //true determines, that this object will receive only video content

Only for iOS and Android

Note that working with video ads is the same as displaying a static banner. The main difference is that you need to use not previously created object, but create it manually indicating that it will work only with video content.

Step 3. Set the delegates🔗

Then you need to install the load delegate (MRGSAdvertisingLoadDelegate protocol) and the show delegate (MRGSAdvertisingShowDelegate protocol). Use the following methods to install them:

// Set the delegate to be called on successful or unsuccessful download operation
// Conforms to MRGSAdvertising.ILoadDelegate
MRGSAdvertising.GetBanner().LoadDelegate = this;

// Set a delegate that will be called at the end of the view
// Conforms to MRGSAdvertising.IShowDelegate
MRGSAdvertising.GetBanner().ShowDelegate = this;
MRGSAdvertising* adv = //...

//install the delegate, which will be called in case of successful or unsuccessful loading operation
[adv setLoadDelegate:self];
//install the delegate, which will be called upon the end of the viewing
[adv setShowDelegate:self];
MRGSAdvert adv = // ...

//install the delegate, which will be called in case of successful or unsuccessful loading operation
adv.setLoadDelegate(this);
//install the delegate, which will be called upon the end of the viewing
adv.setShowDelegate(this);

Step 4. Load the advertising🔗

After installing all the necessary parameters, you need to load the advertising from the MRGS server.

In order to load the content, use the following method:

// Will check for content and load it
// Static
MRGSAdvertising.GetBanner().LoadContent();

// Will check for content and load it
// Video
MRGSAdvertising.GetVideo().LoadContent();
- (void)loadContent;

//I.e.:
MRGSAdvertising* adv = //...
//Initializing and installing the delegates...

[adv loadContent]; //this method will check the availability of the content and load it
//I.e.:
MRGSAdvert adv = // ...
//Initializing and installing the delegates...

adv.loadContent(); //this method will check the availability of the content and load it

After loading the advertising, the delegate object will call one of the following methods:

public void OnAdvertisingLoaded()
{
    // Download completed successfully
}

public void OnAdvertisingLoadingError()
{
    // Ad loading error
}
//Successful loading completion
- (void)onAdvertisingLoaded

//Advertising loading error
- (void)onAdvertisingLoadingError:(MRGSAdvertising*)advertising;
//Successful loading completion
onAdvertisingLoaded()

//Advertising loading error
onAdvertisingLoadingError()

Make sure ads are set up on the server

During the first integration, if you receive a loading error, you need to make sure that creatives and campaigns are created on the MRGS server. In case of such problems, to check and launch test campaigns, please contact the contact indicated on the page with integration steps.

Step 5. Show the advertising🔗

After the advertising is loaded, you can show it to a user. To do that, use the next method:

// Static
// Show ads. Optianally, you can set a payload that will be sent to your server after the ad has been shown.
MRGSAdvertising.GetBanner().ShowContent();

// Video
// Show ads. Optianally, you can set a payload that will be sent to your server after the ad has been shown.
MRGSAdvertising.GetVideo().ShowContent("test_payload");
- (void)showContentFromUIViewController:(UIViewController *)viewController;

//I.e.:
MRGSAdvertising* adv = //...

[adv showContentFromUIViewController:self];
//I.e.:
MRGSAdvert adv = // ...

adv.showContent();

Then the advertising window will be opened. To learn about the finish of the demonstration and the action of the user, a method will be called from the delegate object:

public void OnAdvertisingFinished(bool skipped)
{
    // Finished
}
- (void)onAdvertisingFinished:(MRGSAdvertising*)advertising wasSkipped:(BOOL)skipped;
void onAdvertisingFinished(boolean skipped)

By the skipped flag you can see whether the video has been viewed till the end or not, if your system suggests giving out the reward only in case of the ad was watched till the end.

Important

Before calling a method of showing an ad you need to mute the sound in the game, since the banner may use a video with music. After the callback method of ending the display is initiated, you can turn on the game sound again.

Example🔗

void LoadAdverts{
    // Static
    MRGSAdvertising.GetBanner().LoadDelegate = this;
    MRGSAdvertising.GetBanner().ShowDelegate = this;
    MRGSAdvertising.GetBanner().LoadContent();

    // Video
    MRGSAdvertising.GetVideo().LoadDelegate = this;
    MRGSAdvertising.GetVideo().ShowDelegate = this;
    MRGSAdvertising.GetVideo().LoadContent();
}

public void OnAdvertisingLoaded()
{
    MRGSLog.Instance.AddLog("MRGS OnAdvertisingLoaded: ");
    if (MRGSAdvertising.GetBanner().CanShowContent()){
        MRGSAdvertising.GetBanner().ShowContent();
    }

    if (MRGSAdvertising.getVideo().CanShowContent()){
        //Video Content Loaded
        // Mute the sound in the app, as there may be music in the video
        MRGSAdvertising.GetVideo().ShowContent();
    }
}

public void OnAdvertisingLoadingError()
{
    MRGSLog.Instance.AddLog("MRGS OnAdvertisingLoadingError: ");
}

public void OnAdvertisingFinished(bool skipped)
{
    MRGSLog.Instance.AddLog("MRGS OnAdvertisingFinished: " + skipped);
}
@property (nonatomic, strong) MRGSAdvertising* videoAD;

- (void)viewDidLoad {
    //Static ad
    MRGSAdvertising* staticAD = [[MRGSAdvertisingManager sharedInstance] getAdvertising];
    [staticAD setLoadDelegate:self]; // where self - is an object realizing the MRGSAdvertisingLoadDelegate protocol
    [staticAD setShowDelegate:self]; // where self - is an object realizing the MRGSAdvertisingShowDelegate protocol
    [staticAD loadContent]; // this method will check the availability of the content and load it

    //Video ad
    videoAD = [[MRGSAdvertisingManager sharedInstance] createAdvertising:YES]; //YES determines, that this object will receive only video content
    [videoAD setLoadDelegate:self]; // where self - is an object realizing the MRGSAdvertisingLoadDelegate protocol
    [videoAD setShowDelegate:self]; // where self - is an object realizing the MRGSAdvertisingShowDelegate protocol
    [videoAD loadContent]; // this method will check the availability of the content and will load it
}

#pragma mark - Advertising delegate

- (void)onAdvertisingLoaded:(MRGSAdvertising*)advertising {
    if(advertising == videoAD){
    //Video Content Loaded
    //Mute game sound, since the video may have music
    }

    [advertising showContentFromUIViewController:self];

    //Or
    //[[[MRGSAdvertisingManager sharedInstance] getAdvertising] showContentFromUIViewController:self]; //Receiving ads from the general massive
}

- (void)onAdvertisingLoadingError:(MRGSAdvertising*)advertising {
    NSLog(@"Advertising loading error!");
}

- (void)onAdvertisingFinished:(MRGSAdvertising*)advertising wasSkipped:(BOOL)skipped {
    NSLog(@"Advertising finished! User %@", skipped ? @"skipped" : @"not skipped);
    //Continue working
}
public class AdvertisingManager implements MRGSAdvert.LoadDelegate, MRGSAdvert.ShowDelegate {
    private final MRGSAdvert staticAds;
    private final MRGSAdvert videoAds;

    public AdvertisingManager() {
        staticAds = MRGSAdvertisingFactory.getMRGSAdvertising();
        videoAds = MRGSAdvertisingFactory.createMRGSAdvertising(true);

        staticAds.setLoadDelegate(this);
        staticAds.setShowDelegate(this);

        videoAds.setLoadDelegate(this);
        videoAds.setShowDelegate(this);
    }

    public void loadAdverts() {
        staticAds.loadContent();
        videoAds.loadContent();
    }

    public void showStaticAds() {
        if (staticAds.canShowContent()) videoAds.showContent();
    }

    public void showVideoAds() {
        if (videoAds.canShowContent()) videoAds.showContent();
    }

    @Override
    public void onAdvertisingLoaded() {
        //Advertising can be shown
    }

    @Override
    public void onAdvertisingLoadingError() {
    }

    @Override
    public void onAdvertisingFinished(boolean skipped) {

    }
}

Last update: 2023-10-25
Created: 2020-02-17