Skip to content

api ios

Jump to bottom
BallHawk20 edited this page Jul 25, 2019 · 7 revisions

/*
Title: iOS API reference Description:
Sort: 5 */

Overview

This article documents API classes for the following namespaces:

For a comprehensive integration guide, click here.

UnityAds

Use this namespace to implement basic ad content, such as rewarded or non-rewarded video, interstitial, or banner ads.

#import <UnityAds/UnityAds.h>

Methods

initialize

Initializes the Unity Ads service, with a specified Game ID and test mode status.

+ (void)initialize:(NSString *)gameId
    delegate:(nullable id<UnityAdsDelegate>)delegate
    testMode:(BOOL)testMode
    enablePerPlacementLoad:(BOOL)enablePerPlacementLoad;
}
Parameter Data type Description
gameId NSString The Unity Game ID for your Project, located in the developer dashboard.
delegate UnityAdsDelegate The delegate for UnityAdsDelegate callbacks.
testMode BOOL Set to YES to enable test mode, and NO to disable it. When in test mode, your game will not receive live ads.
enablePerPlacementLoad boolean When set to true, this parameter allows you to load content for a specific Placement prior to displaying it. Please review the load method documentation before enabling this setting.

You can check the initialization status with the following function:

+ (BOOL)isInitialized;

You can check whether the current platform is supported by the SDK with the following function:

+ (BOOL)isSupported;

load

Loads ad content for a specified Placement, allowing for more accurate fill request reporting that is consistent with the standards of most mediation providers. If you initialized the SDK with enablePerPlacementLoad enabled, you must call load before calling show.

Note: The load API is in closed beta and available upon invite only. If you would like to be considered for the beta, please contact Unity Ads.

+ (void)load:(NSString *)placementId;

show

Shows content in the specified Placement, if it is ready.

+ (void)show:(UIViewController *)viewController placementId: (NSString *)placementId;

isReady

Returns whether an ad is ready to be shown for the specified Placement.

+ (BOOL)isReady:(NSString *)placementId;
Parameter Data type Description
placementId NSString The Placement ID, located on the developer dashboard.

You can check whether an ad is ready to be shown for the specified Placement by calling:

+ (BOOL)isReady: (NSString *)placementId;

addDelegate

Adds an active listener for UnityAdsDelegate callbacks.

+ (void)addDelegate:(id<UnityAdsDelegate>)delegate;

removeDelegate

Allows you to remove an active listener delegate.

+ (void)removeDelegate:(id<UnityAdsDelegate>)delegate;

setDebugMode

Controls the amount of logging output from the SDK. Set to true for more robust logging.

+ (void)setDebugMode:(BOOL)enableDebugMode;

You can check the current status for debug logging from the SDK by calling:

+ (BOOL)getDebugMode;

Interfaces

UnityAdsDelegate

An interface for handling various states of an ad. Implement this listener delegate in your script to define logic for rewarded ads. The interface has the following methods:

@protocol UnityAdsDelegate <NSObject>
- (void)unityAdsReady:(NSString *)placementId;
- (void)unityAdsDidStart:(NSString *)placementId;
- (void)unityAdsDidFinish:(NSString *)placementId
    withFinishState:(UnityAdsFinishState)state;
- (void)unityAdsDidError:(UnityAdsError)error withMessage: (NSString *)message;
@end

Note: Unity recommends implementing all of these methods in your code, even if you don’t use them all.

Interface method Description
unityAdsReady Handles logic for ad content being ready to display through a specified Placement.
unityAdsDidStart Handles logic for the player triggering an ad to play.
unityAdsDidFinish Handles logic for an ad finishing. Define conditional behavior for different finish states by accessing the FinishState result from the listener delegate (documented below). For example:

- (void)unityAdsDidFinish: (NSString *)placementId
withFinishState: (UnityAdsFinishState)state {
  if (state == kUnityAdsFinishStateCompleted) {
    // Reward the user for watching the ad to completion.
  } else if (state == kUnityAdsFinishStateSkipped) {
    // Do not reward the user for skipping the ad.
  } else if (state == kUnityAdsFinishStateError) {
    // Log an error message.
  }
}
unityAdsDidError Handles logic for ad content failing to display because of an error.

Enums

UnityAdsFinishState

The enumerated states of the end-user’s interaction with the ad. The SDK passes this value to the unityAdsDidFinish callback after the ad completes.

typedef NS_ENUM(NSInteger, UnityAdsFinishState)
Value Description
kUnityAdsFinishStateError Indicates that the ad failed to complete due to a Unity error.
kUnityAdsFinishStateSkipped Indicates that the user skipped the ad.
kUnityAdsFinishStateCompleted Indicates that the user successfully finished watching the ad.

UnityAdsPlacementState

The enumerated states of a Unity Ads Placement.

typedef NS_ENUM(NSInteger, UnityAdsPlacementState)
Value Description
kUnityAdsPlacementStateReady The Placement is ready to show ads.
kUnityAdsPlacementStateNotAvailable The Placement is not available.
kUnityAdsPlacementStateDisabled The Placement was disabled.
kUnityAdsPlacementStateWaiting The Placement is waiting to be ready.
kUnityAdsPlacementStateNoFill The Placement has no advertisements to show.

Retrieve the UnityAdsPlacementState value with the following function:

+ (UnityAdsPlacementState)getPlacementState:(NSString *)placementId;

UnityAdsError

The enumerated causes of a Unity Ads error.

Value Description
kUnityAdsErrorNotInitialized = 0 The Unity Ads service is currently uninitialized.
kUnityAdsErrorInitializedFailed An error occurred in the initialization process.
kUnityAdsErrorInvalidArgument Unity Ads initialization failed due to invalid parameters.
kUnityAdsErrorVideoPlayerError An error occurred due to the video player failing.
kUnityAdsErrorInitSanityCheckFail Initialization of the Unity Ads service failed due to an invalid environment.
kUnityAdsErrorAdBlockerDetected An error occurred due to an ad blocker.
kUnityAdsErrorFileIoError An error occurred due to inability to read or write a file.
kUnityAdsErrorDeviceIdError An error occurred due to a bad device identifier.
kUnityAdsErrorShowError An error occurred when attempting to show an ad.
kUnityAdsErrorInternalError An internal Unity Ads service error occurred.

UnityAdsBanner

Use this namespace to implement banner ads.

Methods

loadBanner

The basic method for loading banner ad content. You can adjust this function with several parameters, depending on your needs.

Method Description
+ (void)loadBanner; Loads the banner ad with the default Placement ID.
+ (void)loadBanner:(NSString *)placementId; Loads the banner ad with a specific Placement ID (located on the developer dashboard).

For example:

- (void)loadBanner {
    if ([UnityAds isReady:self.bannerPlacementId]) {
        [UnityAdsBanner loadBanner:self.bannerPlacementId];
    }
}

setBannerPosition

Sets the position of the banner ad, using the UnityAdsBannerPosition enum.

+ (void)setBannerPosition:(UnityAdsBannerPosition)bannerPosition;

destroy

Destroys the banner ad, removing it from the view hierarchy and hiding it from the player.

+ (void)destroy;

Interfaces

UnityAdsBannerDelegate

Implement this interface to handle various banner states. The listener delegate includes the following methods:

@protocol UnityAdsBannerDelegate <NSObject>
- (void)unityAdsBannerDidLoad:(NSString *)placementId view: (UIView *)view;
- (void)unityAdsBannerDidUnload:(NSString *)placementId;
- (void)unityAdsBannerDidShow:(NSString *)placementId;
- (void)unityAdsBannerDidClick:(NSString *)placementId;
- (void)unityAdsBannerDidHide:(NSString *)placementId;
- (void)unityAdsBannerDidError:(NSString *)message;
@end

Note: Unity recommends implementing all of these methods in your code, even if you don’t use them all.

Interface method Description
unityAdsBannerDidLoad Called when the Unity banner finishes loading an ad. The view parameter references the banner that should be inserted into the view hierarchy. For example:

- (void)unityAdsBannerDidLoad:(NSString *)placementId view:(UIView *view {
  // Store the bannerView for later:
  self.bannerView = view;
  // Add the banner into your view hierarchy:
  [self.view addSubview:self.bannerView];
}
unityAdsBannerDidUnload Called when ad content is unloaded from the banner, and references to its view should be removed.
unityAdsBannerDidShow Called when the Unity banner is shown for the first time and visible to the user.
unityAdsBannerDidClick Called when the Unity banner is clicked.
unityAdsBannerDidHide Called when the Unity banner is hidden.
unityAdsBannerDideError Called when an error occurs showing the banner.

You can set or retrieves the assigned UnityAdsBannerDelegate for Unity Ads to send banner callbacks to, using the following methods:

+ (void)setDelegate:(id <UnityAdsBannerDelegate>)delegate;

+ (nullable id <UnityAdsBannerDelegate>)getDelegate;

Enums

UnityAdsBannerPosition

The enumerated positions you can set as an anchor for banner ads.

typedef NS_ENUM(NSInteger, UnityAdsBannerPosition) {
    kUnityAdsBannerPositionTopLeft,
    kUnityAdsBannerPositionTopCenter,
    kUnityAdsBannerPositionTopRight,
    kUnityAdsBannerPositionBottomLeft,
    kUnityAdsBannerPositionBottomCenter,
    kUnityAdsBannerPositionBottomRight,
    kUnityAdsBannerPositionCenter,
    kUnityAdsBannerPositionNone
};

UnityMonetization

Use this namespace to implement ads for use with Personalized Placements.

#import <UnityAds/UnityMonetization.h>

Methods

initialize

Initializes Unity Ads in your game at run time. To avoid errors, initialization should occur early in the game’s run-time lifecycle, preferably at boot. Initialization must occur prior to showing ads.

+ (void)initialize:(NSString *)gameId delegate:(nullable id <UnityMonetizationDelegate>)delegate testMode:(BOOL)testMode;
Parameter Description
gameID The Game ID for your Project found on the developer dashboard.
delegate The listener delegate for UnityMonetizationDelegate callbacks.
testMode Indicates whether the game is in test mode. When testMode is true, you will only see test ads. When testMode is false, you will see live ads. It is important to use test mode prior to launching your game, to avoid being flagged for fraud.

isReady

Checks whether a UMONPlacementContent object is ready for the given Placement. Returns YES if content is ready, and NO if it isn’t.

+ (BOOL)isReady:(NSString *)placementId;

Interfaces

UnityMonetizationDelegate

An interface for handling various states of UMONPlacementContent objects. The interface has the following methods:

@protocol UnityMonetizationDelegate <UnityServicesDelegate>
- (void)placementContentReady:(NSString *)placementId
    placementContent:(UMONPlacementContent *)decision;

- (void)placementContentStateDidChange:(NSString *)placementId
    placementContent:(UMONPlacementContent *)placementContent
        previousState:(UnityMonetizationPlacementContentState)previousState
            newState:(UnityMonetizationPlacementContentState)newState;
@end
Interface method Description
placementContentReady Notifies you that a UMONPlacementContent object is available for a given Placement and is ready to show.
placementContentStateDidChange Notifies you when the readied UMONPlacementContent object’s status has changed due to a refresh.

Example UnityMonetizationDelegate implementation:

@interface MyMonetizationDelegate <UnityMonetizationDelegate>
@end

@implementation MyMonetizationDelegate
- (void)placementContentReady:(NSString *)placementId
    placementContent:(UMONPlacementContent *)placementContent {
    if ([placementId isEqualToString:@"video"]) {
        self.interstitial = placementContent;
    } else if ([placementId isEqualToString:@"rewardedVideo"]) {
        self.rewardedVideo = placementContent;
    }
}

- (void)placementContentStateDidChange:(NSString *)placementId
    placementContent:(UMONPlacementContent *)decision
        previousState:(UnityMonetizationPlacementContentState)previousState
            newState:(UnityMonetizationPlacementContentState)newState {
    if (newState != kPlacementContentStateReady) {
        // Disable showing ads because content isn't ready anymore
    }
}
@end

UMONShowAdDelegate

Implement this delegate to provide the unityAdsDidFinish callback method for a video ad’s UnityAdsFinishState. The interface has the following methods:

@protocol UMONShowAdDelegate <NSObject>
- (void)unityAdsDidStart:(NSString*)placementId;
- (void)unityAdsDidFinish:(NSString*)placementId withFinishState:(UnityAdsFinishState)finishState;
@end
Interface method Description
unityAdsDidStart Handles logic for the player triggering an ad to play.
unityAdsDidFinish Implement this method to provide logic for handling whether the ad was completed, skipped, or errored out, depending on the finish state.

Classes

UMONPlacementContent

A class representing monetization content that your Placement can display.

Associated methods:

Method Description
- (BOOL)isReady Returns YES if the UMONPlacementContent object is ready to display, and NO if it isn’t.
- (NSString)getType; Returns the type of UMONPlacementContent available to display. The following string values are valid:

UMONRewardablePlacementContent

Extends the UMONPlacementContent class with functionality to support rewarded content.

Associated methods:

Method Description
- (BOOL)isRewarded Returns YES if the UMONPlacementContent is rewarded, and NO if it isn’t.

UMONShowAdPlacementContent

Extends the UMONRewardablePlacementContent class with functionality to support video ad content.

Method Description
- (void)show:(UIViewController *)viewController withDelegate:(id <UMONShowAdDelegate>)delegate; Displays the available UMONShowAdPlacementContent. Implement a UMONShowAdDelegate delegate to define how this function responds to each ad finish state.

UMONPromoAdPlacementContent

Extends the UMONShowAdPlacementContent class, providing functionality for IAP Promo content. For more information, see documentation on Native Promos.

Enums

UnityAdsFinishState

An enum representing the final state of an ad when finished. Use it to handle reward cases.

Value Description
kUnityAdsFinishStateCompleted The player viewed the ad in its entirety.
kUnityAdsFinishStateSkipped The player skipped the ad before it played in its entirety.
kUnityAdsFinishStateError The ad failed to load.

Example unityAdsDidFinish implementation:

- (void)unityAdsDidFinish:(NSString *)placementId withFinishState:(UnityAdsFinishState)finishState {

    NSLog (@"UnityAds FINISH: %@", placementId);

    if (finishState == kUnityAdsFinishStateCompleted && [placementId isEqualToString: @"rewardedVideo"]) {
        // Reward the player
        ((UMONShowAdPlacementContent *) self.rewardedContent).rewarded = YES;
        NSLog (@"Reward the player");
    }
}

USRVUnityPurchasing

This class manages purchasing adapters, which are interfaces for the SDK to retrieve the information it needs from your custom IAP implementation.

@interface USRVUnityPurchasing: NSObject
+ (void)setDelegate:(id<USRVUnityPurchasingDelegate>)delegate;
+ (nullable id<USRVUnityPurchasingDelegate>)getDelegate;
@end

Methods

UnityPurchasingTransactionCompletionHandler

Your custom game logic for handling a successful transaction, used in a USVRUnityPurchasingDelegate's purchaseProduct method.

UnityPurchasingTransactionErrorHandler

Your custom game logic for handling a failed transaction. The function takes a UPURTransactionDetails object. In the example below, a failed transaction calls UnityPurchasingTransactionErrorHandler, which returns a UPURTransactionError enum.

Interfaces

USVRUnityPurchasingDelegate

An interface for implementing a custom purchasing solution that's compatible with IAP Promo. The interface has the following methods:

typedef void (^UnityPurchasingLoadProductsCompletionHandler) (NSArray<UPURProduct*>*);
typedef void (^UnityPurchasingTransactionCompletionHandler) (UPURTransactionDetails*);
typedef void (^UnityPurchasingTransactionErrorHandler) (UPURTransactionError, NSException*);

@protocol USRVUnityPurchasingDelegate
- (void)loadProducts:(UnityPurchasingLoadProductsCompletionHandler)completionHandler;
- (void)purchaseProduct:(NSString *)productId 

    completionHandler:(UnityPurchasingTransactionCompletionHandler)completionHandler

        errorHandler:(UnityPurchasingTransactionErrorHandler)errorHandler
            userInfo:(nullable NSDictionary *)extras;
@end
Interface method Description
loadProducts The SDK calls this to retrieve the list of available Products. It uses the UnityPurchasingProductsCompletionHandler interface, which takes a UPURProduct object to register your Products (example below).
purchaseProduct The SDK calls this when a user clicks the buy button for a promotional asset. Unity passes the purchased Product’s ID to your in-app purchasing system. The function uses the UnityPurchasingTransactionCompletionHandler and UnityPurchasingTransactionErrorHandler functions to handle the purchase’s success or failure according to your implementation.

Example of an implemented loadProducts function:

- (void)loadProducts:(UnityPurchasingLoadProductsCompletionHandler)completionHandler {

    completionHandler (@[[UPURProduct build:^(UPURProductBuilder *builder){
        builder.productId = @"100BronzeCoins";
        builder.localizedTitle = @"100 Bronze Coins";
        builder.localizedPriceString = @"$1.99";
        builder.localizedPrice = [NSDecimalNumber decimalNumberWithString:@"1.99"];
        builder.isoCurrencyCode = @"USD";
        builder.localizedDescription = @"Awesome Bronze Coins available for a low price!";
        builder.productType = @"Consumable";
    }]]);
}

Example purchaseProduct implementation:

- (void)purchaseProduct:(NSString *)productId completionHandler:(UnityPurchasingTransactionCompletionHandler)completionHandler errorHandler:(UnityPurchasingTransactionErrorHandler)errorHandler userInfo:(nullable NSDictionary *)extras {
    thirdPartyPurchasing.purchase (productId); // Generic developer purchasing function
   
    // If purchase succeeds:
    completionHandler ([UPURTransactionDetails build: ^(UPURTransactionDetailsBuilder *builder) {
        builder.productId = productId;
        builder.transactionId = thirdPartyPurchasing.transactionId;
        builder.currency = @"USD";
        builder.price = [NSDecimalNumber decimalNumberWithString: @"1.99"];
        builder.receipt = @"{\n\"data\": \"{\\\"Store\\\":\\\"fake\\\",\\\"TransactionID\\\":\\\"ce7bb1ca-bd34-4ffb-bdee-83d2784336d8\\\",\\\"Payload\\\":\\\"{ \\\\\\\"this\\\\\\\": \\\\\\\"is a fake receipt\\\\\\\" }\\\"}\"\n}";
    }]);
    
    // If purchase fails:
    errorHandler (kUPURTransactionErrorNetworkError, nil);
}
@end

UMONNativePromoAdapter

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. Pass a UMONPromoAdPlacementContent object through the initWithPromo function to create a new adapter. For example:

`self.nativePromoAdapter = [[UMONNativePromoAdapter alloc] initWithPromo: placementContent];`
Interface method Description
- (void)promoDidShow: (UMONNativePromoShowType)showType; The SDK calls this function when the Promo displays. It should include your custom method for displaying promotional assets. You can pass a UMONNativePromoShowType enum value to reference the preview type of your Promo asset.
- (void)promoDidClose; The SDK calls this function when the player dismisses the Promo offer.
- (void)promoDidClick; The SDK calls this function when the player clicks the button to purchase the Product. It should initiate the purchase flow.

Example UMONNativePromoAdapter 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];
}

Classes

UPURProduct

An IAP product converted into an object that the SDK can use for optimizing monetization.

Set the following fields on the @interface UPURProductBuilder:NSObject builder, then call + (instancetype)build:(void (^) (UPURProductBuilder *))buildBlock to construct the final object:

Builder method Param type Description
productId NSString An internal reference ID for the Product.
localizedTitle NSString A consumer-facing name for the Product, for store UI purposes.
localizedPriceString NSString A consumer-facing price string, including the currency sign, for store UI purposes.
localizedPrice NSDecimalNumber The internal system value for the Product’s price.
isoCurrencyCode NSString The ISO code for the Product’s localized currency.
localizedDescription NSString A consumer-facing Product description, for store UI purposes.
productType NSString Unity supports "Consumable", "Non-consumable", and "Subscription" Product types.

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

UPURTransactionDetails

An IAP transaction receipt converted into an object that the SDK can use for optimizing monetization.

Property Type Description
productId NSString An internal reference ID for the Product.
transactionId NSString An internal reference ID for the transaction.
receipt NSString The JSON fields from the appStoreReceiptURL detailing the transaction. Encode the receipt as a JSON object containing Store, TransactionID, and Payload.
price NSDecimalNumber The internal system value for the Product’s price.
currency NSString The ISO code for the Product’s localized currency.

For more details, see Apple’s documentation on In-App Purchase receipt fields.

Enums

UPURTransactionError

An enum indicating the reason a transaction failed.

typedef NS_ENUM (NSInteger, UPURTransactionError) {
    kUPURTransactionErrorNotSupported,
    kUPURTransactionErrorItemUnavailable,
    kUPURTransactionErrorUserCancelled,
    kUPURTransactionErrorNetworkError,
    kUPURTransactionErrorServerError,
    kUPURTransactionErrorUnknownError
};
NSString *NSStringFromUPURTransactionError (UPURTransactionError);

UPURStore

An enum indicating which store the transaction came from.

typedef NS_ENUM (NSInteger, UPURStore) {
    kUPURStoreNotSpecified,
    kUPURStoreGooglePlay,
    kUPURStoreAmazonAppStore,
    kUPURStoreCloudMoolah,
    kUPURStoreSamsungApps,
    kUPURStoreXiaomiMiPay,
    kUPURStoreMacAppStore,
    kUPURStoreAppleAppStore,
    kUPURStoreWinRT,
    kUPURStoreTizenStore,
    kUPURStoreFacebookStore
};
NSString *NSStringFromUPURAppStore(UPURStore);

UMONNativePromoShowType

The enumerated display types of a Native Promo asset.

Value Description
"FULL" Indicates a full promotional view.
"PREVIEW" Indicates a minimized view that can expand to display the full Promo.
Clone this wiki locally