ADMARVEL SDK VERSION: 2.9.2_Beta2
REQUIRED BASE SDK: 5.0
SUPPORTED DEPLOYMENT TARGET: 3.0 or greater*
*Note: It is crucial that you weak link the specified frameworks below if you want to support lower deployment targets than 4.3.  If you don't weak link the frameworks then your app won't run on lower iOS versions.  The AdMarvel SDK intelligently includes only the supported features on various iOS versions but requires weak linking of the frameworks to achieve this. 


CONTENTS:
---------------
There are two folders that are part of this package:

	AdMarvelSDK
	AdMarvelDemoApps

The AdMarvelSDK folder contains the header files and a library file you will need to use.

The AdMarvelDemoApps folder contains multiple different demo applications that show you how to use the AdMarvel SDK.  These applications come pre-populated with a demo partner id and site id.  We recommend you experiment with these applications first to familiarize yourself with how the SDK works.  Once you receive a partner id and site id from AdMarvel for use with the SDK it would be a good idea to plug them into these demo applications and verify your account is working properly.  


iOS LIB:
---------------
Regardless of whether you are building an iPhone/iPod app, an iPad only app or a universal iOS app you just need to use the AdMarvelSDK library file.  This is assuming you are building with Xcode 4.2 or greater with iOS 5.0 as your base and your deployment target set to iOS 3.0 or greater (deployment target should be 3.2 or greater for iPad only apps).

If you are building using an older version of Xcode and need a version with a lower base SDK that 5.0 let us know and we can provide you with an older release of our SDK.  We don't recommend this though and would suggest upgrading to the newest Xcode and using the AdMarvelSDK library in this package.


INCLUDING SDK: 
---------------
The SDK comprises of one universal library file (works both for simulator and device) and two header files.  First you need to add these to your Xcode project.  Then you need to make sure you have the following frameworks included (these are dynamic libraries so they won't add any size to your application):

	CoreLocation
	EventKit (weak linked if deployment target less than 4.0)
	EventKitUI (weak linked if deployment target less than 4.0)
	Foundation
	iAd (weak linked if deployment target less than 4.3)
	MediaPlayer (weak linked if deployment target less than 4.0)
	MessageUI (weak linked if deployment target less than 4.0)
	QuartzCore
	SystemConfiguration
	UIKit

If you have an AdMarvel SDK with third party SDKs included you will also need to make sure you include all the frameworks required by those SDKs.  Here is a breakdown of required frameworks by SDK:

Medialets SDK:
	AudioToolbox
	AddressBook
	CFNetwork
	CoreLocation
	MediaPlayer
	QuartzCore
	SystemConfiguration
	libsqlite3.0.dylib
	libz.dylib
	libSystem.dylib

Millennial SDK:
	AudioToolbox
	AVFoundation
	CoreGraphics
	CoreLocation
	Foundation
	MediaPlayer
	MobileCoreServices
	QuartzCore
	SystemConfiguration
	UIKit

	* Millennial SDK now requires "-ObjC -all_load" to be set as part of your Other Linker Flags in your project.
	
Google/AdMob SDK:
	AudioToolbox
 	CoreGraphics
	MessageUI
	SystemConfiguration
    
Rhythm SDK:
	CoreLocation
	MediaPlayer
 	MessageUI
	QuartzCore
 	SystemConfiguration


BANNERS:
---------------
You will need to create an AdMarvelDelegate with all your desired configuration.  The only required configuration is your AdMarvel provided partner id and site id and a UIViewController the SDK can use to present full screen modal controllers.  Using this AdMarvelDelegate you will then create an AdMarvelView and add it to your existing view for rendering.  Then you just need to make a getAd* call when you are ready to display your first ad.

For more details please read through all the comments in the AdMarvelView.h and AdMarvelDelegate.h header files.  The various demo applications should also provide a useful example of how to use the SDK.


INTERSTITIALS:
---------------
Interstitials work differently than banners.  You still create an AdMarvelView and provide it with an AdMarvelDelegate with the required configuration and callback methods.  However interstitial AdMarvelView objects are not added to your view hierarchy and instead takeover full screen when displayed.  Interstitials control their own display and dismissal so the app just needs to listen for the appropriate delegate callback methods to know the current state of the interstitial.  Also for interstitials (unlike banners) there are separate methods provided for getting and displaying.  So it is possible to get an interstitial ahead of time and display it later when the app requires.

Regarding interstitial display the app needs to control when interstitials will be displayed since it knows when pages transition and keeps all stats for the user's session.  AdMarvel can control frequency capping for interstitials but this is time based (i.e. don't show more than 1 of this interstitial in 24 hours) not session based.

Generally when developers implement interstitials we recommend the following:

1) If possible define a configurable (i.e. part of the configuration the app downloads on start) number (lets call this X) that defines interstitial frequency (i.e. how many page transitions between interstitial calls). 
2) Define what you want to count as page transitions in the application. 
3) (Optional depending on desired behavior) Define a configurable max number of times (lets call it N) the app will display interstitials for a given session.  This allows the app to make sure that a given user doesn't see more than N interstitials per launch.

Assuming the above configuration options exist then you can basically control how often an interstitial is seen and also the max number of interstitials seen.  The assumption is this is for the "ScreenChange" type of interstitials.  The "AppOpen" launch interstitial is a separate unit and should be called immediately without requiring configuration from the server.

It is also important with multitasking (since iOS 4) to decide what behavior is desired on app resume from background (as opposed to new app launch).  Ideally when resuming an app from background on iOS 4 you would count that as a new launch and try to display the "AppOpen" interstitial and then reset any "ScreenChange" interstitials counters from the last session.

We also recommend that you use the same logic as in our AdMarvelInterstitialDemo application which attempts to pre load the next interstitial after the last one was attempted.  So after app launch (regardless of success/failure) you would pre load the first ScreenChange and after each ScreenChange display attempt (success or failure) you would preload the next one.  It is important that you don't retry interstitial requests though and instead just check the flag isInterstitialReady before deciding to display the interstitial or continue on in the app so the experience is seamless to the user if an interstitials isn't available.


SUPPORTED SDKS:
---------------
Google/AdMob SDK - 5.0.5
Medialets - 2.5.4
Millennial - 4.5.3
Rhythm - 5.1.3

The base SDK includes support for AdMarvel campaigns, server side ad networks and RichMedia providers and iAds.  However we can provide an SDK that supports any combination of the above third party ad network SDKs.


SDK NOTES:
---------------
Google/AdMob:
The new combined SDK is meant to replace both the old AdMob and Google SDKs.  If you are switching to using this new SDK and were previously using one of the older SDKs (AdMob and/or Google) please let our ad support team know (adsupport@admarvel.com) so they can create new tags for the combined SDK and guarantee that only the new tags serve on the new release but the old tags still serve to your previous app versions.  If this is the first time you are integrating the AdMarvel SDK you don't need to worry about this step.

Medialets:
If you have a Medialets enabled AdMarvel SDK please see also look at the README in the Medialets folder in the SDK.  This will give you information for special steps required for initializing Medialets.


FAQ:
---------------
Q) How do I tell what SDK version I have and what ad network SDKs are supported?

A) This should be apparent in the name of the zip file and folder that contained the SDK package.  If you no longer have that you can call the getSDKVersion method on the AdMarvelView.  This will print out the AdMarvel SDK version followed by the names of the ad network SDKs supported.


Q) All I have are the AdMarvel demo partner id and site id.  How do I get my own?

A) You should be able to do testing and early development with the demo ids.  If you are getting close to launching your application or would like to test out the AdMarvel UI then you will need to get an account provisioned.  Please contact support@admarvel.com to get an account provisioned and live ids setup.   


Q) I've added the AdMarvel SDK to my project but I'm not seeing ads.  What is wrong?

A) Please try turing on test mode.  This is done by having the delegate implement testingEnabled and have it return YES.  If you see ads now then it seems like you don't have any actual ads or ad networks provisioned for your account.  If this is the case please contact adsupport@admarvel.com and we can setup whatever ad networks your require.  If you still don't see any ads please double check if the demo application populated with your partner id and site id is displaying ads.  The demo application should always display ads when test mode is enabled so if you are not seeing ads it may be possible that your partner id and site id are not valid.


Q) I have user information available and I want to send it to AdMarvel.  How do I do so?

A) You do this by sending targeting parameters.  To enable this you need to implement the targetingParameters method your AdMarvelDelegate.  The AdMarvel recognized list of targeting parameters can be found as constants at the top of the AdMarvelDelegate.h header file.  The AdMarvelDemo application shows an example of how to send user information.


Q) I want to pass custom targeting parameters to AdMarvel for use with my house campaigns.  How do I do this?

A) Custom targeting parameters are passed as part of the targeting parameters (described in the previous question).  Any name/value pair is allowed as long as the name doesn't conflict with the existing targeting parameters defined at the top of the AdMarvelDelegate.h header file.  To make it easier to avoid naming conflict we recommend you append something custom such as the app name ("appname_") to the key name you use.  You will then be able to target your house campaigns using these parameters in the AdMarvel campaign management UI.


Q) What custom targeting parameters are useful?

A) From our experience here are some useful examples of the information you could provide: section of the application, content type, user settings/preferences, etc.  Basically anything you think could be relevant to help you sell and target advertising campaigns in the future. 


Q) Can I change the size of the AdMarvelView or do I need to stick with 320x50?

A) The AdMarvelView can be whatever size works best for your application.  Generally AdMarvel will assign a different site id for each different size you want to support.  We recommend going with 320x50 for iPhone apps since that is the easiest size to source from ad networks.  For iPad applications it varies a bit more.  Two common sizes are 768x90 (great for header/footer banners as shown in the demo application) or 300x250 (usually when you ad is mixed into the content somewhere).  The 300x250 has the greatest fill across multiple networks. That being said iAds for iPad currently only supports 768x66 and 1024x66.


Q) As opposed to two different library files for simulator and device, now there is single library file, does it mean that size of my app grow significantly when compiled with this library?

A) No. The size of universal library is significantly larger than when compiled into your app, since it contains three different architectures (arm6, arm7 and i386). Only the relevant portion of it will get compiled into your app.


Q) Does AdMarvel use the UDID? 

A) For previous SDKs built with iOS 4.3 the AdMarvel SDK would retrieve the UDID for (1) frequency capping of ad campaigns and (2) compliance with the application  programming interfaces of any Ad Networks selected by customer that require a UDID in order to return an ad.  AdMarvel maintains UDIDs in volatile memory for the sole purposes of frequency capping and session management and deletes UDIDs immediately after they are no longer required for such purposes.


Q) What does AdMarvel do now that uniqueIdentifier has been deprecated in iOS 5?

A) For all SDK releases compiled with iOS 5 we are following the guidelines Apple provides for replacing using the UDID with using a generated UUID:

http://developer.apple.com/library/ios/#documentation/uikit/reference/UIDevice_Class/DeprecationAppendix/AppendixADeprecatedAPI.html#//apple_ref/occ/instp/UIDevice/uniqueIdentifier

The app developer always has an option to provide their own UNIQUE_ID targeting value if they so choose by passing the UNIQUE_ID targeting parameter though if this is not unique this will impact AdMarvel's ability to frequency cap.

 
If you are running into any problems or have any further questions please feel free to email adsupport@admarvel.com for help.