> For the complete documentation index, see [llms.txt](https://intowow.gitbook.io/crystalexpress-documentation-v3-x/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://intowow.gitbook.io/crystalexpress-documentation-v3-x/ios-sdk/api-reference/i2wapi.md). # I2WAPI ## Overview `I2WAPI` is used to set up sdk-wise configurations. The followings are some instruction for better sdk performance using `I2WAPI`. ### SDK Initialization Invoke `+ initWithVerboseLog:isTestMode:` as soon as possible. We recommand doing this within `[AppDelegate application:didFinishLaunchingWithOptions:]`. ### Background Fetch Integrate background fetch to enhance ad fill rate. Please find details [here](/crystalexpress-documentation-v3-x/ios-sdk/advanced-integration/background-fetch.md) ## Interface ### `+ initWithVerboseLog:isTestMode:` #### Declaration ``` + (void) initWithVerboseLog:(BOOL)enableVerbose isTestMode:(BOOL)testMode; ``` #### Parameters | name | description | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | enableVerbose | Always use `NO` for release. Use `YES` to enable SDK debugging verbose log. | | testMode | Always use `NO` for release. Use `YES` if trying to retrive test ad. Since SDK cache this option for a short period, remove you app and reinstall it if switching between normal and test mode repidly. | ### `+ isAdServing` #### Declaration ``` + (BOOL) isAdServing; ``` #### Return Value `NO` if SDK is either turned off or has not yet fetched all metadata for the first time; otherwise, `YES`. ### `+ getCrystalID` #### Declaration ``` + (NSString *) getCrystalID; ``` #### Return Value The crystal id in `crystalexpress.plist`. ### `+ triggerBackgroundFetchOnSuccess:onFail:onNoData:` #### Declaration ``` + (void) triggerBackgroundFetchOnSuccess:(void (^)())success onFail:(void (^)())fail onNoData:(void (^)())noData; ``` #### Parameters | name | description | | ------- | ---------------------------------------------- | | success | the callback block of background fetch success | | fail | the callback block of background fetch fail | | noData | the callback block of background fetch no data | #### Discussion Please find details [here](/crystalexpress-documentation-v3-x/ios-sdk/advanced-integration/background-fetch.md) ### `+ setActivePlacement:` #### Declaration ``` + (void) setActivePlacement:(NSString *)placement; ``` #### Parameters | name | description | | --------- | ------------------------------------------------- | | placement | Placement id that is currently requesting for ad. | #### Discussion Use this api to notify SDK to treat this placemnet more aggressively. ### `+ setActivePlacements:` #### Declaration ``` + (void) setActivePlacements:(NSArray *)placements; ``` #### Parameters | name | description | | ---------- | ------------------------------------------------------------------- | | placements | Array of placement id strings that are currently requesting for ad. | #### Discussion Use this api to notify SDK to treat these placemnets more aggressively. ### `+ setAudienceTargetingUserTags:` #### Declaration ``` + (void) setAudienceTargetingUserTags:(NSSet *)tags; ``` #### Parameters | name | description | | ---- | -------------------------------------------------------------------------------------- | | tags | A set of strings that represent the characteristics of the app or the user of the app. | #### Discussion CrystalExpress™ SDK has a built-in ad retargeting mechanism called audience targeting. App could set proper tags to deliver the ads their users might be interested in. * Tags could be app tags (app setting) or user tags (user demography, preference, or interest). * SDK will only fetch ads that match the tags. Ad operation team could put the tags on ads via CrystalExpress™ Backend. ### `+ handleDeepLinkWithUrl:sourceApplication:` #### Declaration ``` + (void) handleDeepLinkWithUrl:(NSURL *)url sourceApplication:(NSString *)sourceApplication; ``` #### Parameters | name | description | | ----------------- | ------------------------------------------------------------------------------------------- | | url | `url` from `[AppDelegate application:openURL:sourceApplication:annotation:]`. | | sourceApplocation | `sourceApplication` from `[AppDelegate application:openURL:sourceApplication:annotation:]`. | #### Discussion This is used for SDK preview mode integration. Find more details [here](/crystalexpress-documentation-v3-x/ios-sdk/advanced-integration/preview-mode.md). ### `+ setAdUrlLoadingListener:` #### Declaration ``` + (void)setAdUrlLoadingListener:(BOOL(^)(NSString *redirectUrl))adUrlHandler; ``` #### Parameters | name | description | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | adUrlHandler | Block used to handle ad redirect request. Return `YES` to inform SDK not to open this url with any browser/webview. Return `NO` to let SDK open the url with browser/webview. | #### Discussion Use this api only if app is trying to open ad redirect request with its own browser/webview. Make sure to handle the redirect request with app when returning `YES`. ### `+ isAdValid:` #### Declaration ``` + (BOOL)isAdValid:(Ad *)ad; ``` #### Parameters | name | description | | ---- | -------------------------------------------------------- | | ad | `Ad` object containing data for some ad returned by SDK. | #### Discussion Sometimes app may hold an ad from SDK for quite a long time and the ad may expire. In this case app should use this API to check if the ad is still valid before showing it. ### `+ blockAd:placement:reason:description:` #### Declaration ``` + (void)blockAd:(Ad *)ad placement:(NSString *)placement reason:(CEAdBlockReasonCode)reason description:(NSString *)description; ``` #### Parameters | name | description | | ----------- | --------------------------------------------------------- | | ad | `Ad` object from the block ad. | | placement | Placement string with which the blocked is requested. | | reason | Reason code for which the ad is blocked. | | description | String describing the reason for which the ad is blocked. | #### Discussion Use this api to notify SDK not to show this ad again. SDK will not return the same again. ### `+ preloadWithPlacement:` #### Declaration ``` + (void)preloadWithPlacement:(NSString *)placement; ``` #### Parameters | name | description | | --------- | -------------------------------------------------------- | | placement | Placement id for which placement want SDK to prepare ad. | #### Discussion Use this api to notify SDK to prepare ad for this placement immediately. ### `+ isAdAvailableWithPlacement:` #### Declaration ``` + (BOOL)isAdAvailableWithPlacement:(NSString *)placement; ``` #### Parameters | name | description | | --------- | --------------------------------------------------------------------------------- | | placement | Placement id for which placement want SDK to check if there is any available ad. | #### Discussion Use this api to check whether there is any ad available now for the specified placement.