Tapjoy Developers

Developer / SDK Integration

SDK Integration

Download the SDK

SDK Integration Instructions:

Dashboard Integration Guide

NEW: The Tapjoy Dashboard now has a built-in Integration Guide that will walk you through the steps of a Tapjoy integration. You can still use this Getting Started Guide document as a reference if you wish. You can go directly to the Integration Guide for your most recent app, or you can go to the Tapjoy Dashboard, select your app,  go to the "Support" menu in the upper-right, and click "How to Integrate".

Manual Integration

If you want to do the integration purely from the documentation (or you are using Adobe AIR, for which we do not have a Dashboard Integration Guide), you may find the docs for each platform here:

Note: To find your Tapjoy SDK Key please see this link.

PPE (Pay Per Engagement) Integrations

Note that as of April 2019, PPE is no longer available on iOS, as per Apple policy.

If you are an advertiser running a PPE campaign, you must first do a standard advertiser integration (iOS, Android, Unity, AIR), and then follow these additional instructions to instrument the action on which you wish the engagement to trigger.

 

Release Notes:

SDK 12.4.2:

Android released February 5, 2020. Unity released February 6, 2020. iOS released February 7, 2020. Air released Feb 10, 2020.

iOS

  • Version bump to match android

Android

  • Removal of legacy functionality related to custom protocol for install attribution
  • Bug fixes

Unity

  • Bug fixes and features inherited from the iOS and Android versions

Air

  • This version is based on the last 12.3.4 release
  • Removal of legacy functionality related to custom protocol for install attribution
  • 64bit compatibility

SDK 12.4.1:

iOS released January 7, 2020. Android released January 23, 2020.

iOS

  • Added safeguards around setUserIDWithCompletion param
  • Bug fix for the app store

Android

  • Removal of legacy functionality related to custom protocol for install attribution
  • Video UI change.
  • Bug Fixes

Unity

  • Bug fixes and features inherited from the iOS and Android versions

SDK 12.4.0:

Released December 4, 2019.

iOS

  • Support for a customer parameter in currency callbacks (Future product release)
  • Bug Fixes

Android

  • Support for a customer parameter in currency callbacks (Future product release)
  • Bug Fixes

Unity

  • Bug fixes and features inherited from the iOS and Android versions

SDK 12.3.4:

Released October 9, 2019.

iOS

  • Support for SceneDelegate
  • Support of UIAlertController instead of UIAlertView

Android

Unity

  • Bug fixes and features inherited from the iOS and Android versions

SDK 12.3.3:

Released September 20, 2019.

iOS

Android

  • Removed MOAT SDK

Unity

  • Bug fixes and features inherited from the iOS and Android versions

SDK 12.3.2:

Released September 16, 2019.

iOS

  • Removed usage of UIWebView
  • iOS 13 support
  • Removed unused frameworks from the SDK
  • Bug fixes

Android

  • The DISABLE_ANDROID_ID_AS_ANALYTICS_ID connect flag is now on by default
  • Bug fixes

Unity

  • Bug fixes and features inherited from the iOS and Android versions
  • UnityPlayerActivity in TapjoyAndroidManifest.xml has been updated

SDK 12.3.1:

Released June 6, 2019.

Note that Tapjoy is no longer updating the Adobe AIR plugin for the Tapjoy SDK.

iOS

  • Additional video performance enhancements


Android


    

  • Additional video performance enhancements
    • 



    

  • 



Unity


    

  • Bug fixes and features inherited from the iOS and Android versions (including the additional video performance enhancements mentioned in the iOS and Android sections).
    • 



SDK 12.3.0:


Released May 28, 2019.


iOS


    

  • Video performance enhancements
    • 

  • The web-based offerwall (also called tapjoy.com offerwall or TJC offerwall) has been removed to comply with Apple’s policy on incentivized installs. The SDK call to directly link to the web-based offerwall has also been removed.
    • 

  • Added didClick delegate method to TJPlacementDelegate. Note that this delegate will not actually be called until there is back-end server support for it. We expect this to start around mid-June 2019.
    • 



@protocol TJPlacementDelegate <NSObject>
@optional
- (void)didClick:(TJPlacement*)placement;


Android


    

  • Video performance enhancements
    • 

  • Added onClick callback to TJPlacementListener. Note that this callback will not actually be called until there is back-end server support for it. We expect this to start around mid-June 2019.
    • 



public interface TJPlacementListener {
    public void onClick(TJPlacement placement);
}


    

  • Bug Fixes:

      

    • Unnecessary ACCESS_WIFI_STATE permission removed from .aar.
      • 

    

    • 



Unity


    

  • Bug fixes and features inherited from the iOS and Android versions (including the video performance enhancements mentioned in the iOS and Android sections).
    • 

  • Added onClickHandler. Note that this callback will not actually be called until there is back-end server support for it. We expect this to start around mid-June 2019.
    • 



public delegate void OnClickHandler(TJPlacement placement);


AIR


    

  • Bug fixes and features inherited from the iOS and Android versions (including the video performance enhancements mentioned in the iOS and Android sections).
    • 

  • Note that the 12.3.0 AIR plugin does not have support for the click callbacks that was added to the 12.3.0 versions of the Android, iOS, and Unity SDKs.
    • 

  • 12.3.0 will be the last update to the Tapjoy Adobe AIR plugin. Future versions of the SDK will not include an Adobe AIR update.
    • 



SDK 12.2.1:


Released March 14, 2019.


iOS


    

  • Fixed a series of spurious "unable to open object file" warnings when building apps with the iOS SDK.
    • 

  • Fixed orientation issues that came up in some AdMob mediation integrations.
    • 

  • Removed unused code, so SDK is about 10% smaller than previous version. (For more information, see FAQ entry on SDK size.)
    • 



Android


    

  • Tapjoy is changing the way it uses persistent IDs, such as the Android ID. In general, Tapjoy is using these persistent IDs less. These changes will be transparent to most publishers and not require any code changes. Specifically:

      

    • For advertising, Tapjoy’s SDK will try to use the Advertising ID if available. Older versions of Tapjoy’s SDK would pass the Android ID if the advertising ID and mac address (if permitted) was unavailable. As of SDK 12.2.1, Tapjoy’s SDK no longer passes Android ID or mac address for advertising purposes, even if the Advertising ID is unavailable.

        

      • If a publisher wishes to send Android ID for advertising purposes when Advertising ID is not available, they may use the ALLOW_LEGACY_ID_FALLBACK connect flag to override default SDK behavior.
        • 

      • If a publisher wishes to send mac address for advertising purposes when Advertising ID is not available, they may use the same connect flag and must also include the ACCESS_WIFI_STATE permission in their manifest.
        • 

      

      • 

    • For analytics, Tapjoy’s SDK will still send Android ID unless the publisher specifically opts out using the DISABLE_ANDROID_ID_AS_ANALYTICS_ID connect flag.
      • 

    • For analytics, Tapjoy’s SDK no longer uses the mac address.
      • 

    • If a publisher is using Tapjoy Managed Currency, and is not setting a publisher user ID, there is a risk that those users who do not have an Advertising ID may lose their currency balance if the Android ID is no longer sent. For publishers using Tapjoy Managed Currency and who do not set a publisher user ID, we recommend that upon updating to 12.2.1, they use the ALLOW_LEGACY_ID_FALLBACK connect flag to ensure that some ID is sent so their users do not lose their currency balances. We also recommend that they begin setting a publisher user ID, so that they are no longer depending on Android ID to track user currency balances.
      • 

    • The DISABLE_PERSISTENT_IDS connect flag is deprecated, as the SDK’s default behavior is to not use persistent ID’s for advertising purposes.
      • 

    

    • 

  • Removed unused code, so SDK is about 10% smaller than previous version. (For more information, see FAQ entry on SDK size.)
    • 

  • The following Android activities are no longer necessary:

      

    • 

      <activity android:name="com.tapjoy.mraid.view.ActionHandler"
android:configChanges="orientation|keyboardHidden|screenSize" />

<activity android:name="com.tapjoy.mraid.view.Browser"
android:configChanges="orientation|keyboardHidden|screenSize" />
      

      • 

    

    • 

  • Bug Fixes:

      

    • Fix for an infrequent "Fatal Exception: java.lang.RuntimeException: Package manager has died" crash
      • 

    • Fix for crash when SDK key is null
      • 

    • Fix for java.util.ConcurrentModificationException which was caused by insufficient thread-safe mechanism used in AppMonitor.getVisibleActivity() method
      • 

    

    • 



Unity


    

  • Bug fixes and features inherited from the iOS and Android versions
    • 



AIR


    

  • Minimum iOS version is now 8.0. This was done to avoid potential issues with Flash Builder.
    • 

  • Bug fixes and features inherited from the iOS and Android versions
    • 



SDK 12.2.0:


Released November 13, 2018.


This release adds a "user is below consent age" flag that helps publishers monetize their user base while remaining in compliance with COPPA. Note that it is the publisher’s responsibility to implement this function; it is not automatically implemented when the Tapjoy SDK is integrated into an application. Responsibility for overall compliance with COPPA and other applicable laws and regulations remains with the publisher.


In the US, the Children’s Online Privacy Protection Act (COPPA) imposes certain requirements on operators of online services that (a) have actual knowledge that the connected user is a child under 13 years of age, or (b) operate services (including apps) that are directed to children under 13.


Similarly, the GDPR imposes certain requirements in connection with data subjects who are below the applicable local minimum age for online consent (ranging from 13 to 16, as established by each member state).  


For applications that are not directed towards children under 13 years of age, but still have a minority share of users known to be under the applicable minimum age, utilize this method to access Tapjoy’s monetization capability. This method will set ad_tracking_enabled to false for Tapjoy which only shows the user contextual ads. No ad tracking will be done on this user.


iOS


    

  • +(void)belowConsentAge:(BOOL)isBelowConsentAge;

      

    • Setting this to TRUE means the Tapjoy SDK will treat the user as if the "Limit Ad Tracking" switch in their settings is on. This means they will still see Tapjoy ads, but the ads will not be targeted based on user behavior, and the user’s ad behavior will not be tracked by Tapjoy.
      • 

    

    • 



Android


    

  • public static void belowConsentAge(boolean isBelowConsentAge);

      

    • Setting this to TRUE means the Tapjoy SDK will treat the user as if if the "Opt Out of Ads Personalization" switch in their settings is on. This means they will still see Tapjoy ads, but the ads will not be targeted based on user behavior, and the user’s ad behavior will not be tracked by Tapjoy.
      • 

    

    • 

  • Bug Fixes:

      

    • Fix for an infrequent "Fatal Exception: java.lang.NullPointerException" crash.
      • 

    

    • 



Unity


    

  • public static void BelowConsentAge(bool isBelowConsentAge);

      

    • Setting this to TRUE means the Tapjoy SDK will treat the user as if if the "Opt Out of Ads Personalization" switch (Android) "Limit Ad Tracking" switch (iOS) in their settings is on. This means they will still see Tapjoy ads, but the ads will not be targeted based on user behavior, and the user’s ad behavior will not be tracked by Tapjoy.
      • 

    

    • 

  • Bug Fixes inherited from the iOS and Android versions
    • 



AIR


    

  • public static function belowConsentAge(isBelowConsentAge:Boolean):void

      

    • Setting this to TRUE means the Tapjoy SDK will treat the user as if if the "Opt Out of Ads Personalization" switch (Android) "Limit Ad Tracking" switch (iOS) in their settings is on. This means they will still see Tapjoy ads, but the ads will not be targeted based on user behavior, and the user’s ad behavior will not be tracked by Tapjoy.
      • 

    

    • 

  • Bug fixes inherited from the iOS and Android versions
    • 



SDK 12.1.0:


Released October 11, 2018.


iOS


    

  • Note that as of April 2019, the web-based offerwall is no longer available. You can now get a direct link to the web-based Tapjoy offerwall, rather than having the user click on a special offer in the app-based offerwall. Note that to enable the web-based offerwall, you must make sure the ‘Show "More Rewards" banner’ checkbox is checked on your virtual currency screen, and you must have a sufficiently large number of daily users (>100). If you try to obtain the URL for the web-based offerwall when it is not enabled, the call will return an error. Here’s an example:

    [Tapjoy getOfferwallURL:placementName completion:^(NSURL *url, NSDate *expires, NSError *error) {
  if (error) {
     // handle the error
    } 
  else {
     [self openURL:url]; //actually open the web-based offerwall in Safari browser 
    }
 }
];

    

    You can also see an implementation in the TapjoyEasyApp that is in the SDK download folder. Pressing the "Show Offerwall in Safari" button gets the url, and then launches it in the Safari browser.
    • 

  • Removed all code that required special info.plist entries for app approval. As of this release, notes for NSMotionUsageDescription, NSAppleMusicUsageDescription, and NSPhotoLibraryUsageDescription are no longer required. Other usage description requirements were removed in earlier versions of the SDK, so there are no longer any explanatory info.plist entries required by including the Tapjoy SDK in your application.
    • 

  • Bug fixes:

      

    • Several bugs related to rotating the device while Tapjoy ads are showing have been addressed.
      • 

    • Fixed a bug where playing one Tapjoy ad immediately following another ad (using contentDidDisappear) would sometimes fail.
      • 

    • Removed the NSUserDefaults synchronize call, which caused a rare crash.
      • 

    

    • 



Android


    

  • SDK now supports Firebase Cloud Messaging (FCM). Apps using the older Google Cloud Messaging (GCM) system should update to FCM, as this will eventually become an Android requirement. Instructions for using FCM with Tapjoy are in the Android Getting Started Guide for Publishers.
    • 

  • Bug fixes:

      

    • Replaced several instances of SharedPreferences.commit with SharedPreferences.apply to address a rare crash issue.
      • 

    • Orientation issue fix where ad content that had only one orientation (portrait or landscape) could be forced out of that orientation when device was rotated after playback started.
      • 

    • UI of error pop-up updated.
      • 

    

    • 



Unity


    

  • SDK now supports Firebase Cloud Messaging (FCM). Apps using the older Google Cloud Messaging (GCM) system should update to FCM, as this will eventually become an Android requirement. Instructions for using FCM with Tapjoy are in the Unity Getting Started Guide For Publishers.
    • 

  • Bug Fixes:

      

    • Tapjoy’s Unity plugin now respects the Unity project rotation settings on iOS.
      • 

    • Bug fixes inherited from the iOS and Android versions
      • 

    

    • 



AIR


    

  • Note that the Tapjoy AIR plugin does not support push notifications, so the FCM updates do not apply.
    • 

  • Bug fixes inherited from the iOS and Android versions.
    • 



SDK 12.0.0:


Released June 26, 2018.


This release is compatible with iOS 12 and Android 9 "Pie".


iOS


    

  • IAB Open Measurement SDK incorporated into Tapjoy SDK. Publishers do not need to take any additional actions or make any code changes.
    • 

  • Minimum supported iOS version is now iOS 8.
    • 

  • SDK support for programatic mediation is included in this SDK. Server and dashboard support for programmatic mediation will be released at a later date.
    • 

  • The "Get Direct Play Video Ad" button in the sample EasyApp has been fixed.
    • 

  • Note that due to recent updates in bitcode, you will need to use Xcode 9.3 or later with this version of the Tapjoy iOS SDK.
    • 



Android


    

  • IAB Open Measurement SDK incorporated into Tapjoy SDK. Publishers do not need to take any additional actions or make any code changes.
    • 

  • Minimum supported Android version is now API Level 14/Android 4.0/Ice Cream Sandwich.
    • 

  • SDK support for programatic mediation is included in this SDK. Server and dashboard support for programmatic mediation will be released at a later date.
    • 

  • Fix for push notifications when targeting Android O devices
    • 



Unity


    

  • All fixes and features from the iOS and Android SDK updates
    • 

  • Note that due to recent updates in bitcode, you will need to use Xcode 9.3 or later for iOS builds with this version.
    • 



AIR


    

  • All fixes and features from the iOS and Android SDK updates
    • 

  • Note that due to recent updates in bitcode, you will need to use Xcode 9.3 or later for iOS builds with this version.
    • 



SDK 11.12.2 (GDPR release):


Released May 18, 2018.


This release contains features that help publishers comply with the General Data Protection Regulation (GDPR). Each platform (iOS, Android, Unity, AIR) has two new functions. Tapjoy is GDPR-compliant based on "legitimate interest," therefore the following functions are not mandatory. However, we offer these functions for those publishers who wish to pass consent information to Tapjoy. If the publisher implements these functions and the user does not consent, Tapjoy will serve non-interest based content to that user.


These functions can be called before the application calls the Tapjoy Connect function, and should be called before the application requests any content from Tapjoy:


    

  1. A setUserConsent function that takes either "0″ (user does not consent), "1″ (user does consent) or a more detailed consent string. This more detailed string is the consent string is described in the Transparency and Consent Framework as supported by the IAB.
    2. 

  2. 

    An optional "subject to GDPR" flag that can be set to YES/TRUE (if the user is subject to GDPR rules) or NO/FALSE (if the user is not subject to GDPR rules). This function should only be called if the application has made its own determination as to whether GDPR is applicable to the user or not.  If this function is not called, Tapjoy assumes the application has not made such a determination, and therefore Tapjoy makes its own determination of GDPR applicability.
    

    3. 



Implementation details for these functions on each platform are described in the platform sections below.


GDPR FAQ


If a user does not consent or withdraws existing consent, will the Tapjoy SDK still send advertising identifiers to Tapjoy? 


Yes. The functions listed above are designed for interest-based advertising, and they send the user consent status for interest-based advertising to Tapjoy. Therefore, the status of the consent does not disable Tapjoy SDK from sending advertising identifier (IDFA for iOS or GAID for Android) at SDK initialization or during ad requests. 


Tapjoy’s legal basis for compliance is ‘legitimate interest’. However, the publisher’s legal basis for compliance, and consequently their requirement for advertiser identifier collection, could be different than Tapjoy’s.


It is left to application to determine if the Tapjoy SDK should be initialized or not, depending on the application’s compliance need. For example, if an application’s legitimate basis for collection of advertising identifier is consent, and user has not consented, then the Tapjoy SDK should not be initialized for such users. 


If a user from a country that is not covered by GDPR does not consent or withdraws consent, would Tapjoy limit advertising to non-interest-based ads for such a user?


The Tapjoy SDK  provides flexibility to handle different types applications, including applications that have no in-app method for determining whether the user is subject to GDPR or not. 


Therefore, when an Application does not make any determination (i.e. the subjectToGDPR function is not called), Tapjoy servers determine whether the user is subject to GDPR. Then, Tapjoy honors the user’s consent preferences only for ad requests that Tapjoy determines are coming from GDPR-covered users.


If the intent is to allow users from any country to withdraw consent as if they were governed by GDPR, this can be done by calling the subjectToGDPR method with TRUE for all non-consenting users. In this case, Tapjoy’s servers will honor the content of the subjectToGDPR method call, and will not make its own determination as to whether or not the user is covered by GDPR. The publisher may also contact support@tapjoy.com and request that Tapjoy honor the consent preferences of all users of their application, regardless of whether they are covered by GDPR or not. 


iOS


    

  • Added:

      

    • +(void)setUserConsent:(NSString*) value;

        

      • Example:
        
[Tapjoy setUserConsent:@"0″]; // user does not consent
        • 

      

      • 

    • +(void)subjectToGDPR:(BOOL) gdprApplicability;

        

      • Example:
        
[Tapjoy subjectToGDPR:NO]        ;   // This user is not subject to GDPR
        • 

      

      • 

    

    • 

  • Note that due to recent updates in bitcode, you will need to use Xcode 9.3 or later with this version of the Tapjoy iOS SDK.
    • 



Android


    

  • Added:

      

    • public static void setUserConsent(String value);

        

      • Example:
        
Tapjoy.setUserConsent("1"); // user does consent
        • 

      

      • 

    • public static void subjectToGDPR(boolean gdprApplicable);

        

      • Example:
        
Tapjoy.subjectToGDPR(true); // This user is subject to GDP
        • 

      

      • 

    

    • 



Unity


    

  • Added:

      

    • public static void SetUserConsent(string value);

        

      • Example: //User consent string generated according to consent string guidelines Tapjoy.SetUserConsent("BOEFEAyOEFEAyAHABDENAI4AAAB9vABAASA");
        • 

      

      • 

    • public static void SubjectToGDPR(bool gdprApplicable);

        

      • Example:Tapjoy.SubjectToGDPR(true); // This user is subject to GDP
        • 

      

      • 

    • Note that in Unity, if you want the GDPR settings to affect the initial Tapjoy Connect call, you should turn autoconnect OFF in the Tapjoy UI and make the Tapjoy Connect call manually in your own code. Otherwise, the Tapjoy Connect call will be made before the GDPR settings can take effect.
      • 

    

    • 

  • Note that due to recent updates in bitcode, you will need to use Xcode 9.3 or later for iOS builds with this version.
    • 



AIR


    

  • Added:

      

    • public static function setUserConsent(consent:String):void

        

      • Example: //User consent string generated according to consent string guidelines TapjoyAIR.setUserConsent("BOEFEAyOEFEAyAHABDENAI4AAAB9vABAASA");
        • 

      

      • 

    • public static function subjectToGDPR(enable:Boolean):void

        

      • Example:TapjoyAIR.subjectToGDPR(true); // This user is subject to GDPR
        • 

      

      • 

    

    • 

  • Note that due to recent updates in bitcode, you will need to use Xcode 9.3 or later for iOS builds with this version.
    • 



SDK 11.12.1:


Released April 30, 2018.


iOS


    

  • Design update to app store end card experience
    • 

  • Design update to how instructions are displayed for certain types of offerwall offers
    • 

  • Note that due to recent updates in bitcode, you will need to use Xcode 9.3 or later with this version of the Tapjoy iOS SDK.
    • 



Android


    

  • Internal changes and fixes only, no new features
    • 



Unity


    

  • All fixes and features from the iOS and Android SDK updates
    • 

  • Note that due to recent updates in bitcode, you will need to use Xcode 9.3 or later for iOS builds with this version.
    • 



AIR


    

  • All fixes and features from the iOS and Android SDK updates
    • 

  • Note that due to recent updates in bitcode, you will need to use Xcode 9.3 or later for iOS builds with this version.
    • 





SDK 11.12.0:


Released March 29, 2018.


iOS


    

  • Removed requirement for CoreLocation framework.
    • 

  • Removed deprecated "Tapjoy Platform Mediation" functionality. This was a specialized form of mediation that Tapjoy has not supported for almost a year. If you are still using platform mediation, you should not update to this version of the SDK, and we recommend switching to industry-standard adapter mediation. Regular adapter mediation functionality (such as video and interstitial mediation provided by Mopub, ironSource, Fyber, Appodeal, and other mediators) is unaffected by this change.
    • 

  • Bug fixes:

      

    • Fixed some bugs involving video freezing when interrupted by headphone unplug, Siri, or alert pop-up.
      • 

    • Fixed infrequent crash involving  UIColor colorFromHexString.
      • 

    

    • 

  • Fixed infrequent issue where audio from a Tapjoy video could play for a few seconds after an app is restored from the background.
    • 



Android


    

  • Tapjoy’s SDK will no longer trigger the following permissions:

      

    • ACCESS_FINE_LOCATION
      • 

    • ACCESS_COARSE_LOCATION
      • 

    • WRITE_EXTERNAL_STORAGE
      • 

    

    • 

  • Removed deprecated "Tapjoy Platform Mediation" functionality. This was a specialized form of mediation that Tapjoy has not supported for almost a year. If you are still using platform mediation, you should not update to this version of the SDK, and we recommend switching to industry-standard adapter mediation. Regular adapter mediation functionality (such as video and interstitial mediation provided by Mopub, ironSource, Fyber, Appodeal, and other mediators) is unaffected by this change.
    • 

  • Bug Fixes:

      

    • Removed an incorrect error message when Tapjoy video content played from cache and there is no network connection.
      • 

    • Fixed an issue where after returning from Tapjoy content, the offerwall or application would be shown in the incorrect orientation.
      • 

    

    • 



Unity


    

  • Removed an incorrect "Error while downloading Asset Bundle" error message when building for Unity Android.
    • 

  • All fixes and features from the iOS and Android SDK updates
    • 



AIR


    

  • All fixes and features from the iOS and Android SDK updates
    •