Campaigns

Preparation

Remember, you need to configure and initialize the Magify Service to work with purchases and subscriptions.

Campaigns are available only with advanced Magify SDK integration.

Campaign Processing - The Heart of the SDK

Campaign processing is the core functionality of the SDK. To begin your understanding, you can consider that campaigns = application event handlers.

For example, on the level_finished game event we have some campaign, that tells SDK to show Interstitial ad with some configuration and describes the bonus reward for the user.

A campaign only makes sense in conjunction with events, when a request for a campaign is made. If a relevant campaign is available, processing begins. The list of events is predetermined and remains unchanged in the live environment - essentially, these events are hardcoded throughout the project. However, campaigns can vary, and different campaigns can be associated with the same events.

In its general form, triggering an event in the code involves waiting for the completion of an asynchronous method. A crucial point here is that the duration of this method's execution can vary greatly, depending on the campaign. It could finish instantly if no campaign is associated with the event, or it could take a considerable amount of time (potentially even minutes) based on the specific campaign.

It's easier to understand how SDK works with a simple example.

Interstitial ad campaign example

The developer collaborates with the configuration manager to define the application event, for example, level_finished, and specifies when it should trigger - such as when the user presses the Continue button on the result screen. The developer hardcodes the event's invocation, and the configuration manager configures an Interstitial campaign for this event in the admin panel.

For this example, the code might look something like this:

public class ResultScreen : MonoBehaviour
{
    [SerializeField]
    private Button _continueButton;
    [SerializeField]
    private Walled _wallet;

    private void Start()
    {
        _continueButton.OnClickAsObservable()
            .TakeUntilDestroy(this)
            .Subscribe(_ => Continue());
        
        // This is where we determine how to handle the bonuses obtained
        MagifyService.Instance.Obtainer.OnProductObtained
            .TakeUntilDestroy(this)
            .Subscribe(result =>
            {
                // For example 'Type' and 'Quantity' for 'result.Product.Payout' elements might be:
                // 'Coins' and '150'
                // 'Diamonds' and '1'
                foreach (var payout in result.Product.Payout)
                {
                    _wallet[payout.Type] += payout.Quantity;
                }
            });
    }

    private async void Continue()
    {
        _continueButton.interactable = false;
        // this line of code runs the async processing of the campaign 
        // "level_finished" is the application event that the campaign was configured for
        await MagifyService.Instance.RequestCampaignAsync("level_finished");
        _continueButton.interactable = true;

        // Load the next level
    }
}

Start session before any campaigns

Before triggering any event, it's required to await the MagifyService.RequestSessionStartAsync method once after SDK initialization at the start of your application. This method serves as a point of initiating the campaign-related work. Under the hood, this method also triggers and awaits the MagifyService.RequestCampaignAsync method, with Consent Given Event or Session Started Event as the event, as detailed in Magify Settings.

The most appropriate time to call this method is when the game has finished loading (after all loading screens) and the first in-game scene is displayed.

public class Bootstrapper : MonoBehaviour
{
    private async void Awake()
    {
        // Show loading screen
        InitializeApp();
        await SceneManager.LoadSceneAsync("MainMenu");
        // Hide loading screen
        await MagifyService.Instance.RequestSessionStartAsync();
    }

    private void InitializeApp()
    {
        // Initialize your application (sdks, user consent, permission, etc) 
    }
}

Components of the campaign

The following is a description of the basic components of any campaign that can be used in your application. The campaign itself may contain some data, but it may also contain creative and products. as different goals require different sets of data, which results in different types of campaigns.

The campaign itself

All campaigns implement the ICampaign interface, which provides two primary attributes for campaigns: its name and type.

In addition to ICampaign, there are two auxiliary interfaces that allow logical grouping of certain campaigns for more convenient handling: ICampaignWithCreative and ICampaignWithProducts

Campaign types

Each specific campaign has its own type that determines what kind of content the campaign can provide and what data set it is described by.

The type of campaign also affects how it will be processed. Depending on the type of campaign, you can determine whether the campaign is now available for use or not at the launch stage. For example, a campaign that requires ad views will only be available if there is a functioning ad mediator, and an in-app campaign will only be available if there is a functioning store.

CampaignType enum defines all possible campaign types in Magify SDK.

The following campaign types are currently supported in the Magify SDK:

• InApp: To offer a purchase within a game product;
• Subscription: To offer to purchase a subscription;
• Interstitial: To offer to view intermediate ads;
• RewardedVideo: To offer to view rewarded ads;
• Banner: To customize the banner ads;
• Bonus: To offer to receive a free bonus;
• RateReview: To offer to rate an app;
• External: To offer to follow an external link;
• CrossPromo: To offer to view another of your apps;
• Notification: To customize notifications;
• Mixed: A mixed campaign that can include the functionality of all other campaigns.

As well as LTO options:

• LtoInApp;
• LtoSubscription;
• LtoRewardedVideo;
• LtoBonus;
• LtoExternal;
• LtoCrossPromo;
• LtoMixed;

Campaign creatives

Campaign creative refers to a description of the visual representation of any campaign. The campaign may not contain any creative at all or, for example, the creative may be an image or some application prefab.

ICreative interface represents the type of creative content that will be shown to the user during campaign processing. Currently, following types of creatives are supported:

• NoUiCreative: This is an empty creative, meaning nothing will be displayed to the user, and the campaign's actions will commence during processing. For example, a button in the store by clicking on which will immediately open a native window from PlayMarket or AppleStore with a product that the user can buy.
• ImageCreative: This creative contains an image that is configured in the admin panel and will be shown to the user within a frame. For example, after the transition to a new level InApp campaign will be requested, which will first show the user an image of what he will get by purchasing this product, the user can close this creative or click on the purchase button after which the native window from the store for purchasing the product will appear.

• CustomCreative: This is a screen (popup/prefab) embedded in the application, with a configurable screenId from the front-end configuratuion panel. It will be requested from the application during campaign processing. Example can be the same as for ImageCreative but, instead of image, some popup (created directly in Unity by you) will be shown to user.
• BundleCreative: Bundles are entities that are not in the application at the build-time, but are uploaded to the server as asset bundles and downloaded in the runtime game for later display to the user. In our SDK they are represented by default as bundle creatives that you can add for different campaigns. You can read more about building and usage of bundles on the related page.

Campaign products

Most campaigns involve some sort of reward for the user, for example InApp campaign should provide the user with a purchased product, Rewarded Ad campaign should provide the user with some sort of reward for ads viewed. Such rewards want to be configured remotely using the configuration panel, for processing these rewards in our SDK we use campaign products.

ProductDef is the base type for all products that can be offered to the user. In most cases, campaigns can have only one specific type of product (e.g., InAppCampaign offers only InAppProducts, RewardCampaign offers RewardProducts, etc.). However, there is one exception, the MixedCampaign which can contains any type of product.

Currently, the following products are supported:

• InAppProduct: The user is offered to purchase an in-app item.
• SubscriptionProduct: The user is offered to purchase a subscriptions.
• RewardProduct: The user is offered to watch an ad in exchange for a reward.
• BonusProduct: This is simply a reward that the user receives for free.
• InfoProduct: This is also a free reward, often used as news that the user must view and frequently doesn't contain an in-game reward.
• ExternalLinkProduct: The user is redirected to an external link, and upon return, he will receive a reward.

• InternalLinkProduct: The user is redirected to an internal link, and receives a reward (see IAppNavigator for more details).
• CrossPromoProduct: The user is rewarded for seeing ads for another of your apps.