Knowledge base

Native Promo

Overview

Unity IAP provides a simple webview interface for you to display IAP promotional assets through Placements. To control the rendering process for these assets, use Native Promo to implement custom promotional displays.

Requirements

To use Native Promo, you must download and install the latest SDK (3.0+) from the Asset Store.

Configuring IAP Promos

Follow the instructions for setting up IAP Placements, Products, and Promos, but note that you should not upload creative assets when configuring your IAP Products.

Using a Native Promo adapter

The SDK provides a Native Promo adapter interface with methods for handling promotional asset interactions. Use these methods in your custom scripts to inform the SDK when the Promo begins, finishes, and initiates the purchase flow.

Unity (C#)

Implementation

Every developer’s Native Promo implementation varies greatly. The following abstract sample code illustrates an implementation.

using UnityEngine.Monetization;

public class NativePromoDisplay : MonoBehaviour {    

    PlacementContent placementContent = Monetization.GetPlacementContent (placementId);

    PromoAdPlacementContent promoContent = placementContent as PromoAdPlacementContent;

    INativePromoAdapter adapter = Monetization.CreateNativePromoAdapter (promoContent);

    void ShowPromo () {

        LogPromoInfo ();

        // Use promoContent’s associated Product ID (e.g. adapter.metadata.premiumProduct.productID) to determine which assets to show

        // Call adapter.OnShown () to tell the SDK the Promo has started, then execute your custom display for those assets

        // Call adapter.OnClicked () to tell the SDK the player clicked the purchase button and to initiate the purchase flow

        // Call adapter.OnClosed () to tell the SDK the Promo has ended      

    }

    void LogPromoInfo () {

        Debug.LogFormat ("Product ID: \t{0}", adapter.metadata.premiumProduct.productId);

        Debug.LogFormat ("Localized Title: \t{0}", adapter.metadata.premiumProduct.localizedTitle);

        Debug.LogFormat ("Localized Description: \t{0}", adapter.metadata.premiumProduct.localizedDescription);

        Debug.LogFormat ("ISO Currency Code: \t{0}", adapter.metadata.premiumProduct.isoCurrencyCode);

        Debug.LogFormat ("Localized Price: \t{0}", adapter.metadata.premiumProduct.localizedPrice);

        Debug.LogFormat ("Localized Price String: \t{0}", adapter.metadata.premiumProduct.localizedPriceString);

    }
}

API Reference

PromoAdPlacementContent

Extends the ShowAdPlacementContent class, providing functionality for IAP Promo content.

Product

A Unity IAP Product object.

Property Retrieval method Description
string productId GetProductId () An internal reference ID for the Product.
string localizedTitle GetlocalizedTitle () A consumer-facing name for the Product, for store UI purposes.
string localizedPriceString GetLocalizedPriceString () A consumer-facing price string, including the currency sign, for store UI purposes.
double localizedPrice GetLocalizedPrice () The internal system value for the Product’s price.
string isoCurrencyCode GetIsoCurrencyCode () The ISO code for the Product’s localized currency.
string localizedDescription GetLocalizedDescription () A consumer-facing Product description, for store UI purposes.
string productType GetProductType () Unity supports "Consumable", “Non-consumable”, and “Subscription” Product Types.

For more details on Product properties, see documentation on Defining Products.

CreateNativePromoAdapter

Pass a PromoAdPlacementContent object through this function to create a new INativePromoAdapter. For example:

INativePromoAdapter adapter = Monetization.CreateNativePromoAdapter (promoContent);

INativePromoAdapter

This interface provides access methods for handling user interaction with promotional assets. Use these methods to pass in your custom assets and define expected behavior.

PromoMetadata

This property contains information for a PromoAdPlacementContent object passed through the adapter.

public struct PromoMetadata {
    public Product premiumProduct;
}

public PromoMetadata metadata { get; };

For example:

string cc = nativePromoAdapter.metadata.premiumProduct.isoCurrencyCode;

OnShown

Call this function when the Promo is shown. It should include your custom method for displaying promotional assets.

void OnShown ();

OnClosed

Call this function when the player dismisses the Promo offer.

void OnClosed ();

OnClicked

Call this function when the player clicks the button to purchase the Product. It should initiate the purchase flow.

void OnClicked ();

Back to top

iOS (Objective-C)

Implementation

Every developer’s Native Promo implementation varies greatly. The following abstract sample code illustrates an implementation.

@interface ViewController: UIViewController <USRVUnityPurchasingDelegate>

-(void) showPromo: (UMONPromoAdPlacementContent *) placementContent {
    self.nativePromoAdapter = [[UMONNativePromoAdapter alloc] initWithPromo: placementContent];
    UMONPromoMetaData *metaData = placementContent.metadata;
    UPURProduct *product = metaData.premiumProduct;
    NSString *price = (product == nil || product.localizedPriceString == nil) ? @"$0.99": product.localizedPriceString;

    self.nativePromoView.hidden = NO;
    NSString *title = [NSString stringWithFormat: @"Buy for only %@", price];
    [self.purchaseButton setTitle: title forState: UIControlStateNormal];
    [self.nativePromoAdapter promoDidShow];    
}

// If the player clicked the purchase button:
(IBAction) purchaseButtonTapped: (id) sender {
    [self.nativePromoAdapter promoDidClick];
    [self.nativePromoAdapter promoDidClose];
    self.nativePromoView.hidden = YES;
}

// If the player closed the promotional asset:
-(IBAction) promoCloseButtonTapped: (id) sender {
    self.nativePromoView.hidden = YES;
    [self.nativePromoAdapter promoDidClose];
}

- (void) loadProducts: (UnityPurchasingLoadProductsCompletionHandler) completionHandler {
    // Retrieve your Products list (see purchasing integration docs) 
}

- (void) purchaseProduct: (NSString *) productId
     // Insert logic for successful or failed product purchase (see purchasing integration docs) 
}

Read the purchasing integration for iOS documentation for more details on the USRVUnityPurchasingDelegate class referenced here.

API Reference

UMONPromoAdPlacementContent

Extends the UMONShowAdPlacementContent class, providing functionality for IAP Promo content.

UMONPromoProduct

A Unity IAP Product object.

Property Description
@property (strong, nonatomic, readonly) NSString *productId An internal reference ID for the Product.
@property (strong, nonatomic, readonly) NSString *localizedTitle () A consumer-facing name for the Product, for store UI purposes.
@property (strong, nonatomic, readonly) NSString *localizedPriceString A consumer-facing price string, including the currency sign, for store UI purposes.
@property (nonatomic, readonly) double *localizedPrice The internal system value for the Product’s price.
@property (strong, nonatomic, readonly) NSString *isoCurrencyCode The ISO code for the Product’s localized currency.
@property (strong, nonatomic, readonly) NSString *localizedDescription A consumer-facing Product description, for store UI purposes.
@property (strong, nonatomic, readonly) NSString *productType Unity supports "Consumable", “Non-consumable”, and “Subscription” Product Types.

For more details on Product properties, see documentation on Defining Products.

initWithPromo

Pass a UMONPromoAdPlacementContent object through this function to create a new UMONNativePromoAdapter.

-(instancetype) initWithPromo: (UMONPromoAdPlacementContent *) promo;

UMONNativePromoAdapter

This delegate provides access methods for handling user interaction with promotional assets. Use these methods to pass in your custom assets and define expected behavior.

UMONPromoMetaData

This property contains information for a UMONPromoAdPlacementContent object passed through the adapter.

@interface UMONPromoAdPlacementContent: UMONShowAdPlacementContent

-(instancetype) initWithPlacementId: (NSString *) placementId withParams: (NSDictionary *) params;

@property (nonatomic, strong, readonly) UMONPromoMetaData *metadata;

@end

promoDidShow

Call this function when the Promo is shown. It should include your custom method for displaying promotional assets.

-(void) promoDidShow;

-(void) promoDidShow: (UMONNativePromoShowType) showType;

You can pass a UMONNativePromoShowType enum value to reference the preview type of your Promo asset. kNativePromoShowTypeFull indicates a full promotional view, while kNativePromoShowTypePreview indicates a minimized view that can expand to display the full Promo.

promoDidClose

Call this function when the player dismisses the Promo offer.

-(void) promoDidClose;

promoDidClick

Call this function when the player clicks the button to purchase the Product. It should initiate the purchase flow.

-(void) promoDidClick;

Back to top

Android (Java)

Implementation

Every developer’s Native Promo implementation varies greatly. The following abstract sample code illustrates an implementation.

UnityPurchasing.setAdapter (new UnityPurchasingAdapter ());

private class UnityPurchasingAdapter implements IPurchasingAdapter {

    @Override
    public void retrieveProducts (IRetrieveProductsListener listener) {
        // Retrieve your Products list (see purchasing integration docs)    
    }

    @Override
    public void onPurchase (String productID, ITransactionListener listener, Map<String, Object> extras) {
        // Insert logic for successful or failed product purchase (see purchasing integration docs)
    }

    private void showPromo (final PromoAdPlacementContent placementContent) {
        final NativePromoAdapter nativePromoAdapter = new NativePromoAdapter (placementContent);

        PromoMetadata metadata = placementContent.getMetadata ();
        Product product = metadata.getPremiumProduct ();
        String price = product == null ? "$0.99": product.getLocalizedPriceString ();

        final View root = getLayoutInflater ().inflate (R.layout.unitymonetization_native_promo, (ViewGroup) findViewById (R.id.unityads_example_layout_root));

        Button buyButton = root.findViewById(R.id.native_promo_buy_button);
        Button closeButton = root.findViewById (R.id.native_promo_close_button);
        buyButton.setText ("Buy now for only " + price + "!");

        nativePromoAdapter.onShown();
        buyButton.setOnClickListener(new View.OnClickListener() {
        @Override
        public void onClick (View v) {
            // Do purchase then call
            nativePromoAdapter.onClosed ();
            ((ViewGroup)root).removeView (findViewById (R.id.native_promo_root));
        }
    });

    closeButton.setOnClickListener (new View.OnClickListener () {
        @Override
        public void onClick(View v) {
            nativePromoAdapter.onClosed ();
            ((ViewGroup)root).removeView (findViewById (R.id.native_promo_root));
        }
    });
}

Read the purchasing integration for Android documentation for more details on the UnityPurchasingAdapter class referenced here.

API Reference

PromoAdPlacementContent

Extends the ShowAdPlacementContent class, providing functionality for IAP Promo content.

Product

A Unity IAP product object.

Property Retrieval method Description
String productId getProductId () An internal reference ID for the Product.
String localizedTitle getlocalizedTitle () A consumer-facing name for the Product, for store UI purposes.
String localizedPriceString getLocalizedPriceString () A consumer-facing price string, including the currency sign, for store UI purposes.
Double localizedPrice getLocalizedPrice () The internal system value for the Product’s price.
String isoCurrencyCode getIsoCurrencyCode () The ISO code for the Product’s localized currency.
String localizedDescription getLocalizedDescription () A consumer-facing Product description, for store UI purposes.
String productType getProductType () Unity supports "Consumable", “Non-consumable”, and “Subscription” Product Types.

For more details on Product properties, see documentation on Defining Products.

NativePromoAdapter

This delegate provides access methods for handling user interaction with promotional assets. Use these methods to pass in your custom assets and define expected behavior. Pass a PromoAdPlacementContent object through the NativePromoAdapter function to create a new adapter. For example:

final NativePromoAdapter nativePromoAdapter = new NativePromoAdapter (placementContent);
PromoMetaData

This property contains information for a PromoAdPlacementContent object passed through the adapter.

public PromoMetadata getMetadata ();

onShown

Call this function when the Promo is shown. It should include your custom method for displaying promotional assets.

public void onShown (NativePromoShowType type);

You can pass a NativePromoShowType enum value to reference the preview type of your Promo asset. FULL indicates a full promotional view, while PREVIEW indicates a minimized view that can expand to display the full Promo.

onClosed

Call this function when the player dismisses the Promo offer.

public void onClicked

onClicked

Call this function when the player clicks the button to purchase the Product. It should initiate the purchase flow.

public void promoClicked;

Back to top

Still need help? Get in touch!
Last updated on 16th Nov 2018