SDK Integration | Appodeal

SDK Integration

App key

Download SDK

Current Gideros Plugin version 2.1.4

The Appodeal SDK is distributed as static library. You can download it here and unzip it. Current version of Appodeal SDK is 2.1.4.

You can read changelog of current version here

Gideros Integration

SDK and Plugin Integration

You should integrate gideros plugin only after your gideros project was exported to XCode project. Download plugin from here, unzip it and drag and drop "Ads" folder to your project in XCode

45d29d72a5802325e108eab805731c32

Also you should add following frameworks to your Build phases:

  • AdSupport
  • AudioToolbox
  • AVFoundation
  • CFNetwork
  • CoreFoundation
  • CoreGraphics
  • CoreImage
  • CoreLocation
  • CoreMedia
  • CoreMotion
  • CoreTelephony
  • EventKit
  • EventKitUI
  • libc++
  • libsqlite3.dylib
  • libxml2.2.dylib
  • libz.dylib
  • MediaPlayer
  • MessageUI
  • MobileCoreServices
  • QuartzCore
  • Security
  • Social
  • StoreKit
  • SystemConfiguration
  • Twitter
  • UIKit
  • WebKit
  • JavaScriptCore
  • CoreBluetooth
  • GLKit
  • SafariServices
94076f4eb8a0c8b69ecfd4e6bf5aea04

After that download the latest version of Appodeal SDK and extract it. Then drag and drop "Resources" folder and "Appodeal.framework" to your project frameworks

4ac4326ab2277faddd89fe000550e0a4

Don't forget to change your bundle identifier and set version of app in XCode project

68747470733a2f2f73332e616d617a6f6e6177732e636f6d2f6170706f6465616c2d696d616765732f53637265656e2b53686f742b323031352d30382d31382b61742b31332e35362e31302e706e67

Ad Types

In your *.lua where you are integrating appodeal gideros plugin define this variables:

local INTERSTITIAL = 1

local VIDEO = 2

local BANNER = 4

local BANNER_BOTTOM = 8

local BANNER_TOP = 16

local NATIVE_AD = 32

local REWARDED_VIDEO = 128

local ALL = 191

Ad types can be combined using bit.bor function (to use it you must add require "bit"). For example bit.bor(VIDEO, INTERSTITIAL)

SDK Initialization

To initialize SDK you need to add following code to the beginning of your gideros project:

require "ads"
require "bit"
appodeal = Ads.new("appodeal")
appodeal:setKey(param1, param2, param3, param4, param5)

where:

param1 is appKey ( "fee50c333ff3825fd6ad6d38cff78154de3025546d47a84f" )

Note: appKey is the key you received when you created an app.

param2 is ad Type ( bit.bor(BANNER, INTERSTITIAL) )

param3 enables or disables autocache ( "false" / "true" )

param4 enables or disables testMode ( "false" / "true" )

param5 disables network for all ad types (Available networks: "amazon_ads", "applovin", "chartboost", "mopub", "unity_ads", "mailru", "facebook", "adcolony", "vungle", "yandex", "startapp", "avocarrot", "flurry", "pubnative", "cheetah", "inner-active", "revmob")

params 3-5 are optional

To initialize only interstitials use appodeal:setKey(appKey, INTERSTITIAL)

To initialize only skippable videos use appodeal:setKey(appKey, VIDEO)

To initialize only rewarded video use appodeal:setKey(appKey, REWARDED_VIDEO)

To initialize interstitials and videos use appodeal:setKey(appKey, bit.bor(VIDEO, INTERSTITIAL))

To initialize only banners use appodeal:setKey(appKey, BANNER)

Display Ad

appodeal:showAd(adTypes)

To display interstitial use appodeal:showAd(INTERSTITIAL)

To display skippable video use appodeal:showAd(VIDEO)

To display rewarded (nonskippable) video use appodeal:showAd(REWARDED_VIDEO)

To display interstitial or video use appodeal:showAd(bit.bor(VIDEO, INTERSTITIAL))

To display banner at the bottom of the screen use appodeal:showAd(BANNER_BOTTOM)

To display banner at the top of the screen use appodeal:showAd(BANNER_TOP)

How to integrate native ads

First you should create native ad view, where you will displa native ad

appodeal:createNativeAdViewWithFrame([x], [y], [width], [height])

If you want to add MediaView to your native ad view add this code:

appodeal:addMediaViewToNativeViewWithFrame([x], [y], [width], [height])

After you have added all needed components you should load native ad with the following code:

appodeal:loadNativeAd(nativeAdType) //nativeAdType can be "APDNativeAdTypeAuto", "APDNativeAdTypeNoVideo", "APDNativeAdTypeVideo"

After native ad was loaded you should attach it to the native ad view you created earlier. To do this you should create callback for native ad (in this callback you can also get all native ad attributes):

appodeal:addEventListener("nativeAdLoadedWithAttributes", function(e)
  appodeal:attachNativeAdToView()
   nativeTitle = e.nativeTitle
   nativeSubtitle = e.nativeSubtitle
   nativeDescriptionText = e.nativeDescriptionText
   nativeStarRating = e.nativeStarRating
   nativeCallToActionText = e.nativeCallToActionText
   nativeContentRating = e.nativeContentRating
   nativeImageUrl = e.nativeImageUrl
   nativeImageHeight = e.nativeImageHeight
   nativeImageWidth = e.nativeImageWidth
   nativeIconImageHeight = e.nativeIconImageHeight
   nativeIconImageWidth = e.nativeIconImageWidth
   nativeIconImageUrl = e.nativeIconImageUrl
end)

If received native ad contains adChoicesView then you should attach it to native ad view:

appodeal:attachAdChoicesViewIfExistsWithFrame([x], [y], [width], [height])

Hiding Banner

To hide banner you need to call the following code:

appodeal:hideAd(BANNER)

Segments and placements

Segments

Segments are divisions of your user base, which share commonalities such as age, sex, location, interests, income bracket, etc. There are several ways to segment users into groups including the use of demographics, in-app behavior or engagement analysis, interests and personal profile data, and location.

Once user segments have been created, they can then be analyzed and used to configure ads.

To create new segment go here

1) Enter it's name

2) Select match rule:

  • ALL - user will only match to segment if all of the rules will apply to them
  • ANY - user will match to segment if any of the rules will apply to them

3) Select platform

4) Select rules that apply to the user, you can select as many rules as you want or none at all:

  • App - match users in one or multiple of your apps
  • SDK version - match users that only use specified sdk version or range of versions
  • Device type - match users that using tablet and/or phone
  • App version - match users that only use specified app version or range of versions
  • Country - match users only from specified countries
  • OS version - match users that are using devices with specified Android
  • Has app installed - only match users that have specified apps installed
  • Session count - match users that had specified number of sessions in your app
  • Average session length - match users with specified that spent specified average session length in your app
  • Device model - match user on specified devices
  • Connection type - match users using specified connection type
  • Gender, Age, Occupation, Relation - matches users with specified Gender, Age, Occupation, Relation
  • Last session time - matches users that last used your app at the specified time
  • Bought inapps - matches users that made in app purchases(tracked using Appodeal.trackInAppPurchase method)
  • Inapp sum, Inapp sum all apps - matches users the spent specified amount in your the app or all apps (only counts inapps tracked using Appodeal.trackInAppPurchase method)
  • Hour, Day - matches users using the app at the specified time
  • NSUInteger, CGFloat, NSString, Bool - matches users using custom parameters. You can set custom parameters in SDK using this:
//all params should be enclosed in quotes
appodeal:setCustomBoolRule("default", "true")
appodeal:setCustomIntRule("asdasd", "12")
appodeal:setCustomDoubleRule("default", "0.123")
appodeal:setCustomStringRule("asdasd", "sadasdasdas")

5) Segment settings. You can apply following settings for each segment, they will apply to all users matched to that segment.

  • Disable networks. Allows you to disable any network for ant ad type it supports
  • Min pricefloor. Allows you to set minimum price floor for each ad type. Ads with eCPM lower then price floor will not be filled.
  • Overriden eCPM. Allows you to override eCPM of each network for ad type. High eCPM(100+) will ensure that the network will be at the top of the waterfall and get the first fill. Low eCPM (close to 0) will ensure that the network acts as backfill

If you have no segments all users will be matched to hidden default segment

If you have multiple segments their order is important. Only the first segment in which rules are matched to the user will apply, all of the rest will be ignored.

Placements

Appodeal SDK allows you to tag each impression with different placement.

To show an ad with placement you have to call show method with your placement name as additional parameter:

appodeal:showAd(BANNER_BOTTOM, "name_of_placement")

Placement can be used for separating your revenue by placement in our dashboard and determining which placement earns you more money

Also you can configure your impression logic for each placement. You can use the following Placement settings:

  • Disable ads - disables ads completely for that placement
  • Disable as types - disables specific ad type for a placement. If you integrated to show INTERSTITIAL | SKIPPABLE_VIDEO you can disable interstitials or skippable video for the placement
  • Reward - you can set a reward amount and name which will be passed in onRewardedVideoFinished callback for all videos shown with this placement
  • Impression/Refresh period - you can set impression period (in seconds) for interstitials, skippable and rewarded video shown with the placement. If the period between two impression is less than impression period second impression will not be shown. For banners and MRECs you can set their refresh period
  • Min pricefloor - Allows you to set minimum price floor for each ad type. Ads with eCPM lower then price floor will not be show.

Placements can only be used as part of existing segment. If you only want to use placements create one segment for each platform without any rules and match rule ALL, all of your users will match to it.

If you have no placement, or call Appodeal.show with placement that do not exist or without placement in your segment the impression will be tagged with 'default' placement and it's settings will be applied

You can check more examples here

Advanced Features

Setting Interstitial callbacks

appodeal:addEventListener(Event.AD_RECEIVED, function(e)
  if e.type=="interstitial" then
  end
end)
appodeal:addEventListener(Event.AD_FAILED, function(e)
  if e.type=="interstitial" then
  end
end)
appodeal:addEventListener(Event.AD_ACTION_BEGIN, function(e)
  if e.type=="interstitial" then
  end
end)
appodeal:addEventListener(Event.AD_DISMISSED, function(e)
  if e.type=="interstitial" then
  end
end)
appodeal:addEventListener(Event.AD_DISPLAYED, function(e)
  if e.type=="interstitial" then
  end
end)

Setting skippable video callbacks

appodeal:addEventListener(Event.AD_RECEIVED, function(e)
  if e.type=="skippablevideo" then
  end
end)
appodeal:addEventListener(Event.AD_FAILED, function(e)
  if e.type=="skippablevideo" then
  end
end)
appodeal:addEventListener(Event.AD_DISMISSED, function(e)
  if e.type=="skippablevideo" then
  end
end)
appodeal:addEventListener(Event.AD_DISPLAYED, function(e)
  if e.type=="skippablevideo" then
  end
end)
appodeal:addEventListener(Event.AD_ACTION_END, function(e)
  if e.type=="skippablevideo" then
  end
end)

Setting rewarded video callbacks

appodeal:addEventListener(Event.AD_RECEIVED, function(e)
  if e.type=="rewarded" then
  end
end)
appodeal:addEventListener(Event.AD_FAILED, function(e)
  if e.type=="rewarded" then
  end
end)
appodeal:addEventListener(Event.AD_DISMISSED, function(e)
  if e.type=="rewarded" then
  end
end)
appodeal:addEventListener(Event.AD_DISPLAYED, function(e)
  if e.type=="rewarded" then
  end
end)
appodeal:addEventListener(Event.AD_ACTION_END, function(e)
  if e.type=="rewarded" then
  end
end)

Setting banner callbacks

appodeal:addEventListener(Event.AD_RECEIVED, function(e)
  if e.type=="banner" then
  end
end)
appodeal:addEventListener(Event.AD_FAILED, function(e)
  if e.type=="banner" then
  end
end)
appodeal:addEventListener(Event.AD_ACTION_BEGIN, function(e)
  if e.type=="banner" then
  end
end)
appodeal:addEventListener(Event.AD_DISPLAYED, function(e)
  if e.type=="banner" then
  end
end)

Setting Native Ad callbacks

appodeal:addEventListener("nativeAdLoadedWithAttributes", function(e)
  //native ad was loaded
end)

appodeal:addEventListener(Event.AD_FAILED, function(e)
  if e.type=="native" then
     //native ad failed to load
  end
end)

Manual ad caching

appodeal:loadAd(adTypes)

You should disable automatic caching before SDK initialization using appodeal:setKey(appKey, adTypes, "false").

To cache interstitial use appodeal:loadAd(INTERSTITIAL)

To cache skippable video use appodeal:loadAd(VIDEO)

To cache rewarded video use appodeal:loadAd(REWARDED_VIDEO)

To cache interstitial and video use appodeal:loadAd(bit.bor(VIDEO, INTERSTITIAL))

To cache banner use appodeal:loadAd(BANNER)

Enabling or disabling automatic caching

appodeal:setKey(appKey, adTypes, "false")

To disable automatic caching for interstitials use appodeal:setKey(appKey, INTERSTITIAL, "false")

To disable automatic caching for skippable videos use appodeal:setKey(appKey, VIDEO, "false")

To disable automatic caching for rewarded videos use appodeal:setKey(appKey, REWARDED_VIDEO, "false")

To disable automatic caching for banners use appodeal:setKey(appKey, BANNER, "false")

To disable automatic caching for all ads use appodeal:setKey(appKey, ALL, "false")

Samples

Display interstitial after it was loaded

require "ads"
require "bit"

local INTERSTITIAL   = 1
local VIDEO          = 2
local BANNER         = 4
local BANNER_BOTTOM  = 8
local BANNER_TOP     = 16
local NATIVE_AD	     = 32
local REWARDED_VIDEO = 128
local ALL            = 191

appodeal = Ads.new("appodeal")
appodeal:setKey(appKey, INTERSTITIAL, "false")
appodeal:loadAd(INTERSTITIAL)

appodeal:addEventListener(Event.AD_RECEIVED, function(e)
  if e.type=="interstitial" then
    appodeal:showAd(INTERSTITIAL)
  end
end)

Display interstitial after app launch

require "ads"
require "bit"

local INTERSTITIAL   = 1
local VIDEO          = 2
local BANNER         = 4
local BANNER_BOTTOM  = 8
local BANNER_TOP     = 16
local NATIVE_AD	    = 32
local REWARDED_VIDEO = 128
local ALL            = 191

appodeal = Ads.new("appodeal")
appodeal:setKey(appKey, INTERSTITIAL, "false")
appodeal:showAd(INTERSTITIAL)

Preparing Your Apps

To avoid a major drop in revenue publishers should turn off App Transport Security until further notice.

To ensure monetization with some adnetworks in Appodeal is not impacted, publishers should add the following to their plist file to allow any insecure connection:

<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <true/>
</dict>

Developers can also edit the plist by adding NSAppTransportSecurity key of dictionary type with a dictionary element of NSAllowsArbitraryLoads of boolean type set to "Yes".

Dictionary key

Add this key in Info.plist , if you use this function in your app

<key>NSBluetoothPeripheralUsageDescription</key>
<string>Advertising</string>
<key>NSCalendarsUsageDescription</key>
<string>Advertising</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Advertising</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Advertising</string>

Bitcode Setting in Xcode 7+

You may see which adapters support Bitcode here - https://github.com/appodeal/appodeal-ios-sdk-mobile-adapters.

Attention. Not all adapters support Bitcode. You can disable this option.

Bitcode

Updating Your IDFA Settings

When you submit your application to the App you need to update its "Advertising Identifier (IDFA)" settings in order to comply with Apple advertising policy.

On the "Advertising Identifier" section:

  • Turn-on "Yes" on the right pane
  • Opt-in the "Serve advertisements within the app" checkbox
  • Opt-in the confirmation checkbox under "Limit Ad tracking setting in iOS"
Idfa