AdColony Class Reference

Inherits from NSObject
Declared in AdColony.h

Overview

The AdColony interface constists of a set of static methods for interacting with the SDK.

Starting AdColony

+ configureWithAppID:zoneIDs:options:completion:

Configures AdColony specifically for your app; required for usage of the rest of the API.

+ (void)configureWithAppID:(NSString *)appID zoneIDs:(NSArray<NSString*> *)zoneIDs options:(nullable AdColonyAppOptions *)options completion:(nullable void ( ^ ) ( NSArray<AdColonyZone*> *zones ))completion

Parameters

appID

The AdColony app ID for your app.
zoneIDs

An array of at least one AdColony zone ID string.
options

(optional) Configuration options for your app.
completion

(optional) A block of code to be executed upon completion of the configuration operation. Dispatched on main thread.

Discussion

This method returns immediately; any long-running work such as network connections are performed in the background. AdColony does not begin preparing ads for display or performing reporting until after it is configured by your app. The required appID and zoneIDs parameters for this method can be created and retrieved at the Control Panel. If either of these are nil, app will be unable to play ads and AdColony will only provide limited reporting and install-tracking functionality. Please note the completion handler. You should not start requesting ads until it has fired. If there is a configuration error, the set of zones passed to the completion handler will be nil.

See Also

Declared In

AdColony.h

Requesting Ads

+ requestInterstitialInZone:options:success:failure:

Requests an AdColonyInterstitial.

+ (void)requestInterstitialInZone:(NSString *)zoneID options:(nullable AdColonyAdOptions *)options success:(void ( ^ ) ( AdColonyInterstitial *ad ))success failure:(nullable void ( ^ ) ( AdColonyAdRequestError *error ))failure

Parameters

zoneID

The AdColony zone identifier string indicating which zone the ad request is for.
options

An AdColonyAdOptions object used to set configurable aspects of the ad request.
success

A block of code to be executed if the ad request succeeds.
failure

(optional) A block of code to be executed if the ad request does not succeed.

Discussion

This method returns immediately, before the ad request completes. If the request is successful, an AdColonyInterstitial object will be passed to the success block. If the request is unsuccessful, the failure block will be called and an AdColonyAdRequestError will be passed to the handler.

See Also

Declared In

AdColony.h

+ requestNativeAdViewInZone:size:options:viewController:success:failure:

Requests an AdColonyNativeAdView.

+ (void)requestNativeAdViewInZone:(NSString *)zoneID size:(CGSize)size options:(nullable AdColonyAdOptions *)options viewController:(UIViewController *)viewController success:(void ( ^ ) ( AdColonyNativeAdView *ad ))success failure:(nullable void ( ^ ) ( AdColonyAdRequestError *error ))failure

Parameters

zoneID

The AdColony zone identifier string indicating which zone the ad request is for.
size

The desired width and height of the native ad view.
options

An AdColonyAdOptions object used to set configurable aspects of the ad request.
success

A block of code to be executed if the ad request succeeds.
failure

(optional) A block of code to be executed if the ad request does not succeed.

Discussion

This method returns immediately, before the ad request completes. If the request is successful, an AdColonyNativeAdView object will be passed to the success block. If the request is unsuccessful, the failure block will be called and an AdColonyAdRequestError will be passed to the handler.

See Also

Declared In

AdColony.h

Zone

+ zoneForID:

Retrieves an AdColonyZone object.

+ (nullable AdColonyZone *)zoneForID:(NSString *)zoneID

Parameters

zoneID

The AdColony zone identifier string indicating which zone to return.

Return Value

An AdColonyZone object. Returns nil if an invalid zone ID is passed.

Discussion

AdColonyZone objects aggregate informative data about unique AdColony zones such as their identifiers, whether or not they are configured for rewards, etc. AdColony zone IDs can be created and retrieved at the Control Panel.

See Also

Declared In

AdColony.h

Device Identifiers

+ getAdvertisingID

Retrieves the device’s current advertising identifier.

+ (NSString *)getAdvertisingID

Return Value

The device’s current advertising identifier.

Discussion

The identifier is an alphanumeric string unique to each device, used by systems to facilitate ad serving. Note that this method can be called before configureWithAppID:zoneIDs:options:completion.

Declared In

AdColony.h

+ getUserID

Retrieves a custom identifier for the current user if it has been set.

+ (NSString *)getUserID

Return Value

The identifier for the current user.

Discussion

This is an arbitrary, application-specific identifier string for the current user. To configure this identifier, use the setOption:withStringValue method of the AdColonyAppOptions object you pass to configureWithAppID:zoneIDs:options:completion. Note that if this method is called before configureWithAppID:zoneIDs:options:completion, it will return an empty string.

See Also

Declared In

AdColony.h

App Options

+ setAppOptions:

Sets the current, global set of AdColonyAppOptions.

+ (void)setAppOptions:(AdColonyAppOptions *)options

Parameters

options

The AdColonyAppOptions object to be used for configuring global options such as a custom user identifier.

Discussion

Use the object’s option-setting methods to configure currently-supported options.

Declared In

AdColony.h

+ getAppOptions

Returns the current, global set of AdColonyAppOptions.

+ (nullable AdColonyAppOptions *)getAppOptions

Return Value

The current AdColonyAppOptions object being used by the SDK.

Discussion

Use this method to obtain the current set of app options used to configure SDK behavior. If no options object has been set, this method will return nil.

See Also

Declared In

AdColony.h

Custom Messages

+ sendCustomMessageOfType:withContent:reply:

Sends a custom message to the AdColony SDK.

+ (void)sendCustomMessageOfType:(NSString *)type withContent:(nullable NSString *)content reply:(nullable void ( ^ ) ( _Nullable id reply ))reply

Parameters

type

The type of the custom message. Must be 128 characters or less.
content

The content of the custom message. Must be 1024 characters or less.
reply

A block of code to be executed when a reply is sent to the custom message.

Discussion

Use this method to send custom messages to the AdColony SDK.

Declared In

AdColony.h

In-app purchase (IAP) Tracking

+ iapCompleteWithTransactionID:productID:price:currencyCode:

Reports IAPs within your application.

+ (void)iapCompleteWithTransactionID:(NSString *)transactionID productID:(NSString *)productID price:(nullable NSNumber *)price currencyCode:(nullable NSString *)currencyCode

Parameters

transactionID

An NSString representing the unique SKPaymentTransaction identifier for the IAP. Must be 128 chars or less.
productID

An NSString identifying the purchased product. Must be 128 chars or less.
price

(optional) An NSNumber indicating the total price of the items purchased.
currencyCode

(optional) An NSString indicating the real-world, three-letter ISO 4217 (e.g. USD) currency code of the transaction.

Discussion

Note that this API can be used to report standard IAPs as well as those triggered by AdColony’s IAP Promo (IAPP) advertisements. Leveraging this API will improve overall ad targeting for your application.

Declared In

AdColony.h

SDK Version

+ getSDKVersion

Retrieve a string-based representation of the SDK version.

+ (NSString *)getSDKVersion

Return Value

The current AdColony SDK version string.

Discussion

The returned string will be in the form of “...”

Declared In

AdColony.h