Welcome to the guide on integrating AdsPostX into your iOS application. This comprehensive documentation is designed to assist developers in seamlessly incorporating AdsPostX Offers into their iOS Apps. Whether you're looking to monetize your app or enhance user engagement, AdsPostX provides a powerful solution. Before getting started, please ensure that you already have an account with AdsPostX. If you don't have an account yet, you can easily create a new one now. Once you have your account credentials, you can proceed with the integration process outlined in this guide. Let's dive in and explore the features and functionalities of the AdsPostX iOS SDK to unlock the full potential of AdsPostX within your iOS Application.
Before you begin the integration process, make sure you have the following requirements in place:
- iOS Build Support Tools: You must install Xcode and the necessary build support tools. Xcode is available for download from the Mac App Store. Install Xcode and follow the installation instructions to set up the required development tools.
- Cocoapods: Cocoapods is a dependency manager for iOS projects. CocoaPods simplifies the process of integrating third-party libraries into your iOS project. Install CocoaPods by running the following command in your terminal:
Here's a quick walkthrough from installation to showing Offers to get you started on the fastest route.
Standard Integration through Cocoapods:
Ensure that your XCode Project meets the minimum deployment target requirements:
The minimum deployment target for your XCode Project should be iOS 13+.
- Open your client app iOS project-workspace (*.xcworkspace) in XCode.
- Select your project at PROJECT level. On the Right side, Under info section, you will find Deployment Target Section. Under it, you will find iOS Deployment Target, make sure it is ≥ 13.0
4. Select your project at TARGETS level. Under General → Minimum Deployments make sure the value for iOS is ≥ 13.0
5. Open a Pod file, If you are using a global platform, check to make sure platform :ios, '13.0’. (OR any value above 13.0 will work) has been updated.
Having these requirements in place will allow you to proceed with the integration of the AdsPostX iOS SDK smoothly.
Depending on your iOS app requirements, please follow the appropriate guide below.
Before integrating AdsPostX into your iOS app, we recommend that you download and build our demo app to familiarize yourself with the code and implementation methods.
Steps to build and run the demo app:
- Unzip the downloaded file
- Open the DemoApp folder.
- Open DemoApp.xcodeproj with Xcode.
- Select either a system-connected iOS device or simulator and then select Run.
- If you are running the demo app on a device, make sure a valid provision profile is selected before running the demo app on the device.
Obtain the latest version of the AdsPostX iOS SDK by using the link below:
- Unzip the downloaded zip file.
- Extract its contents into a directory.
- It will contain AdsPostX.xcframework.
- Follow the instructions below to integrate AdsPostX with your mobile app.
- In the directory that contains the files that were extracted, locate the AdsPostX.xcframework file.
- Drag and drop AdsPostX.xcframework into your Xcode project.
- Select the project and then navigate to the General tab.
- Expand the Frameworks, Libraries, and Embedded Content section.
- Select Embed & Sign / Embed for AdsPostX.xcframework.
This guide assumes that you are familiar with CocoaPods and know how to install dependencies for iOS development. For more information, check out CocoaPods's user guides.
Make sure you have already setupCocoaPods.
Add the AdsPostX to podfile.
Install/Update the pods:
Open the Terminal, navigate to client app project root directory and type:
This guide assumes that you are familiar with Swift Package Manager and know how to install dependencies for iOS development. For more information, check out Swift Package Manager's user guides.
- Go to File > Add Packages
- Then, paste URL:https://github.com/AdsPostX/AdsPostX-iOS-Distribution-SPM.git in the search bar, it will show AdsPostX-iOS-Distribution-SPM in a list, Select Up to Next Major with 1.0.7.
- Wait for the process to finish.
- Select Add Package button.
That's it! You should now see an AdspostX package in the project window as depicted below.
Please note that the AdsPostX version number may be different from the image below depending upon which version you have installed.
There are two ways to integrate AdsPostX into your iOS App.
Native Ads API Integration Native Ads API provides a highly flexible implementation method. With Native Ads API, you can retrieve Offers in a JSON response and then parse and display them according to your specific requirements. The JSON response contains individual fragments that make up an Offer, giving you full control over how the ad is rendered. This method allows for deep customization and styling to seamlessly blend the Offers into your app's UI.
Standard Integration If you prefer a quick and straightforward way to display AdsPostX Offers without the need for extensive customization, the Standard integration is a suitable option. It offers a pre-built modal box that can be easily integrated into your iOS App. While it may not provide the same level of customization as Native Ads, the Standard integration does allow basic theming options that can be controlled through the AdsPostX dashboard. This option is ideal for those who prioritize simplicity and quick implementation.
Once you've installed the AdsPostX iOS SDK using the step(s) above, you can simply use the getOffers call to retrieve Offers. You will need your SDK ID in order to do so.
Import AdsPostX in your iOS Project.
Here is an example of a fully-formed call using the getOffers method:
where Offer struct as follows:
SDK ID as provided
dictionary [String: Any]
User payload parameters and other filters/options
It returns a Result object with a dictionary or error details.
dictionary [String: Any]
contains offers details.
contains error info
The getOffers method is effectively a wrapper around the AdsPostX Native Ads API which you can learn more about here. The payload and options values can be passed through and used interchangeably with the Native Ads API.
In the example above, the parameters parameter is passing user payload information including country and firstname. The payload parameter also includes a creatives: 1 option to instruct AdsPostX to only return Offers that have at least one creative.
The getOffers response object will contain Offers if Offers are available and can then be parsed to display them using the Offers fragments provided.
To accurately report events such as impressions, opt-outs, etc, each Offer contains beacon URL to fire based on the nature of the event. For impressions, use the pixel attribute. For other events, refer to the beacons attribute to handle. For example, if the user presses "No thanks" on the offer, fire the no_thanks_click beacon URL.
A successful call to getOffers would return a JSON response (in a dictionary form) as follows:
A failed call to getOffers would return an error response similar to the following:
Integration consists of three steps:
- Initializing the SDK
- Loading Offers
- Displaying Offers
Include the AdsPostX initialization code anywhere in the app, but make sure to call it before loading and showing offers.
Also, make sure to import AdsPostX.
SDK ID as provided
A callback will be sent on this closure with the type Result.
Once the SDK is initialized successfully, call the load function to load Offers.
The load function must be called at least once before showing Offers.
attributes and their values you want to send to AdsPostX.
Note: All attributes must be passed based on the supported list below.
A callback will be sent on this closure with type Result.
Currently, the following attributes are supported
Load() with Attributes:
Load() without Attributes:
Once initWith and load calls are successful, call showOffers to display offers in your app.
can be either fullScreen or popup
can be either true or false
the default value is true
if transparent = true, the background will be transparent.
if transparent = false, the background will be non-transparent.
tuple(UInt, UInt, UInt, UInt) optional
1st parameter: describes top margin in %.
2nd parameter: describes bottom margin in %.
3rd parameter: describes left margin in %.
4th parameter: describes right margin in %.
margin values must be >= 0 and <= 15
Default margin values for top margin, bottom margin, left margin, right margin is 5 (ie. 5%).
Callback to run each time an offer is displayed
Callback that runs when there is an error. Provides a error info.
Callback to run each time an offer is dismissed
The margin will be calculated based on the orientation. If the device is in landscape orientation, the margin will be calculated considering the device height. If the device is in portrait orientation, the margin will be calculated considering the device width.
If margin value is > 15 then it will consider only 15.
After displaying offers, the load function must be called again before displaying offers again.
Showing Offers along with margins and transparency:
Showing Offers without margins and transparency:
The default value for Environment is .live.
We recommend using .test only in development, not in production.
Make sure to call this method before the initWith() call.
By default, Debug Log is disabled.
Enabling Debug Log will give you more debug information related to offers.
We recommend enabling logs only in development, not in production.
Make sure to call this method before the initWith() call.
Also, add the following code to the client application's 'AppDelegate' method supportedInterfaceOrientationsFor window
if the client app supports all orientations.
if the client app supports only portrait orientation.
if the client app supports only landscape orientation.
if client app supports all orientations except UpsideDown.
If you're running into any issues while going through the integration process, feel free to contact us at firstname.lastname@example.org.