Please follow the instructions below to integrate our Unity SDK into your app.
1. SDK Implementation
a. Prerequisites
- Unity 5 or higher
- For iOS deployment:
- iOS version 8 or higher
- For Android deployment
- Android version 4.0.3 (API level 15) or higher
- Google Play services 7.5 or higher
b. Integration
- Download our Unity plugin, by clicking here.
- Open your project in the Unity editor. Select Assets -> Import Package -> Custom Package and open the Personaly.unitypackage file.
- Make sure that all files from the list are selected and click on Import.
Android
The Google Play Services library is included in the plugin and can be replaced with a different version if required. Note that it is a required library.
Use the following code in case your project needs proguard:
-dontwarn com.google.**
-dontwarn com.android.**
-dontwarn android.webkit.**
-dontwarn com.unity3d.player.UnityPlayer
-keepattributes *Annotation*, Exceptions, Signature, Deprecated, SourceFile, SourceDir, LineNumberTable, LocalVariableTable, LocalVariableTypeTable, Synthetic, EnclosingMethod, RuntimeVisibleAnnotations, RuntimeInvisibleAnnotations, RuntimeVisibleParameterAnnotations, RuntimeInvisibleParameterAnnotations, AnnotationDefault, InnerClasses
-keep class com.google.** { *; }
-keep class com.android.** { *; }
iOS
In your Unity project, navigate to Menu -> Edit -> Project Settings -> Player -> iOS Settings -> Target Minimum iOS version and make sure it is set to 8.0 or higher.
- Once you’ve created the Xcode project, drag and drop Personaly.framework to it and navigate to Project Settings -> General -> Embedded Binaries -> Tap + -> Choose Personaly.framework.
- Navigate to Project Settings -> Build Phases ->Tap + -> New Run Script Phase and paste the following code into the script text field:
bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/Personaly.framework/strip-frameworks.sh"
This step is required in order to work around an App Store submission bug when archiving universal binaries.
c. Initialization
The APP_ID key can be found on our dashboard after you’ve finished setting up a new app. Use the following method to set up the SDK:
Personaly.Configure (name, APP_ID);Note: You cannot pass anything but the internal property name as the first parameter, otherwise callbacks won’t work.
Optionally, set the gender, date of birth in the format “yyyy/MM/dd”, the age and userId when initiallizing:
Config config = new Config ()
.SetAge (19)
.SetGender (Config.Gender.MALE)
.SetDateOfBirth ("1989/07/23")
.SetUserId ("USER_ID");
Personaly.Configure(name, APP_ID, config);
The USER_ID should be unique and defined for the current user.
Our SDK has the ability to retrieve a result from a callback during the initialization process. To use it, add the following interface implementation of
Personaly.ConfigureCallback:
public void ConfigureSuccess(){
// Initialization has been successfully performed
}
public void ConfigureFailure (string result){
// An error occurred while initializing
CallbackResult callback = CallbackResult.Create(result);
int errorCode = callback.errorCode;
string message = callback.errorMessage;
}
d. Error codes
Our callbacks contain error codes that help identify errors and debug them. The error codes are received in the failure methods of the Personaly callbacks:
// Error occured on incorrect sdk initialization - due to wrong or empty ad keys (appId, placementId, etc...)
int ERROR_INIT = 1;
// Internal error occured in sdk, not related to the publisher
int ERROR_INTERNAL = 2;
// The ad request was unsuccessful due to a network connectivity issues or a resource that was not found
int ERROR_NETWORK = 3;
// The ad failed to load.
int ERROR_NO_AD = 4;
// The ad is loading or currently being displayed, please wait
int ERROR_BUSY_AD = 5;
e. Auto-caching
The SDK pre-caches Rewarded Moment/Interstitial placements just after being initialized as well as just after displaying an ad. However, you can disable this behavior by setting auto caching to false and pre-cache manually instead (not recommended):
Personaly.setAutoCaching (true);
f. Test Mode
In order to activate the test mode for a specific device, do the following:
- Launch the app and find the TEST_MODE_ID in the logs.
Android
D/TEST_MODE_ID: Add TEST_MODE_ID: 854g5d22-36f8-45da-9482-efbdd6cdjnc5 to list of devices in order to use TEST_MODE
IOS
PERSONALY LOG: Copy your IDFA here: 261C78E9-DAE5-4A75-9494-FBA3F427D3A5
- Open the Test integration page on your dashboard
- Add the TEST_MODE_ID to the list of your test devices.
2. Rewarded Video/Playable ad
a. Prerequisites
Before you start working with the ad unit, please make sure that the SDK is integrated and initialized as described here.
b. Auto-Cache (recommended)
This ad unit has the ability to load multiple campaigns with different placement IDs. It can be loaded automatically or manually. By default this ad has auto caching enabled, but it can be changed in any moment and from any place of the project.
Auto caching pre-caches the next ad for a particular placement just after displaying an ad.
To disable auto-caching you will have to manually pre-cache the ad.
Personaly.setAutoCaching (true);
c. Implementation
The REWARDED_PLACEMENT_ID key can be found in our dashboard (as placement id) after you define a new ad placement for a Rewarded Moment in the ad settings page.
Use the following code to start pre-caching an ad:
Personaly.PrecacheCampaign (name, REWARDED_PLACEMENT_ID);Note: You cannot pass anything but the internal property name as the first parameter, otherwise callbacks won’t work.
Interactive Moments have relatively large file sizes, so we recommend pre-caching as early as possible when caching manually.
A new ad with the same REWARDED_PLACEMENT_ID can be loaded only if the previous ad is not currently loading. The ideal way is to resolve this is to use the CloseCampaignCallback(string result) method of the callback or call PrecacheCampaign method after the ShowCampaign method.
d. Setting up the Callback
Implement Personaly.CampaignCallback to receive callbacks from the rewarded video/playable ad.
public void PrecacheCampaignCallback(string result){
// the ad caching is finished and ad ready to show
CallbackResult callback = CallbackResult.Create(result);
string placementId = callback.placementId;
}
public void CloseCampaignCallback(string result){
// the ad is closed
CallbackResult callback = CallbackResult.Create(result);
string placementId = callback.placementId;
}
public void FailureCampaignCallback(string result){
// an error occurred while working with ad
CallbackResult callback = CallbackResult.Create(result);
int errorCode = callback.errorCode;
string message = callback.errorMessage;
string placementId = callback.placementId;
}
public void CanViewCampaignCallback(string result){
// result of capping, the ad can be viewed
CallbackResult callback = CallbackResult.Create(result);
string placementId = callback.placementId;
bool canView = callback.canView;
}
public void DidReceiveRewardCampaignCallback(string result){
// result with amount of rewarding
CallbackResult callback = CallbackResult.Create(result);
string placementId = callback.placementId;
int amount = callback.amount;
}
e. Displaying an ad
First, ensure that an ad is loaded in the PrecacheCampaignCallback() method of the callback.
Use the following code if the ad is loaded and ready to be displayed:
Personaly.ShowCampaign (name, REWARDED_PLACEMENT_ID);Note: You cannot pass anything but the internal property name as the first parameter, otherwise callbacks won’t work.
To check that ad has not met its cap, use the following method:
Personaly.CanViewCampaign (name, REWARDED_PLACEMENT_ID);
Note: You cannot pass anything but the internal property name as the first parameter, otherwise callbacks won’t work.
f. Rewarding your user
Rewarded ads offer two possible postback methods: Server to server or Client Side. When using the Client Side method, please check for a reward with the following callback method:
public void DidReceiveRewardCampaignCallback(string result){
// result with amount of rewarding
CallbackResult callback = CallbackResult.Create(result);
string placementId = callback.placementId;
int amount = callback.amount;
}
3. Interstitial Video/Playable ad
a. Prerequisites
Before you start working with the ad unit, please make sure that the SDK is integrated and initialized as described here.
b. Auto-Cache (recommended)
This ad unit has the ability to load multiple campaigns with different placement IDs. It can be loaded automatically or manually. By default this ad has auto caching enabled, but it can be changed in any moment and from any place of the project.
Auto caching pre-caches the next ad for a particular placement just after displaying an ad.
Personaly.setAutoCaching (true);
c. Implementation
The INTERSTITIAL_PLACEMENT_ID key can be found in our dashboard (as placement id) after you define a new ad placement in the Interstitial tab on the ad settings page.
Use following code to start pre-caching an ad:
Personaly.PrecacheCampaign (name, INTERSTITIAL_PLACEMENT_ID);Note: You cannot pass anything but the internal property name as the first parameter, otherwise callbacks won’t work.
Interactive Moments have relatively large file sizes, so we recommend pre-caching as early as possible when caching manually.
A new ad with the same INTERSTITIAL_PLACEMENT_ID can be loaded only if the previous ad is not currently loading. The ideal way is to resolve this is to use the CloseCampaignCallback(string result) method of the callback or call PrecacheCampaign method after the ShowCampaign method.
d. Setting up the Callback
Implement Personaly.CampaignCallback to receive callbacks from the interstitial video/playable ad.
public void PrecacheCampaignCallback(string result){
// the ad caching is finished and ad ready to show
CallbackResult callback = CallbackResult.Create(result);
string placementId = callback.placementId;
}
public void CloseCampaignCallback(string result){
// the ad is closed
CallbackResult callback = CallbackResult.Create(result);
string placementId = callback.placementId;
}
public void FailureCampaignCallback(string result){
// an error occurred while working with ad
CallbackResult callback = CallbackResult.Create(result);
int errorCode = callback.errorCode;
string message = callback.errorMessage;
string placementId = callback.placementId;
}
public void CanViewCampaignCallback(string result){
// result of capping, the ad can be viewed
CallbackResult callback = CallbackResult.Create(result);
string placementId = callback.placementId;
bool canView = callback.canView;
}
public void DidReceiveRewardCampaignCallback(string result){
// using for rewarded ad
}
e. Displaying an ad
First, ensure that the ad is loaded in the PrecacheCampaignCallback (string result) method of the callback.
Use the following code if the ad is loaded and ready to display:
Personaly.ShowCampaign (name, INTERSTITIAL_PLACEMENT_ID);Note: You cannot pass anything but the internal property name as the first parameter, otherwise callbacks won’t work.
To check that ad has not met its cap, use the following method:
Personaly.CanViewCampaign(name, INTERSTITIAL_PLACEMENT_ID);
Note: You cannot pass anything but the internal property name as the first parameter, otherwise callbacks won’t work.
4. Rewarded Pop up ad
a. Prerequisites
Before you start working with the ad unit, please make sure that the SDK is integrated and initialized as described here.
b. Implementation
The REWARDED_POPUP_PLACEMENT_ID key can be found in our dashboard (as placement id) after you define a new ad placement in the Rewarded Pop-up tab on the ad settings page.
Use the following code to start pre-caching an ad:
Personaly.PrecacheRewardedPopup (name, REWARDED_POPUP_PLACEMENT_ID);Note: You cannot pass anything but the internal property name as the first parameter, otherwise callbacks won’t work.
Videos and playable ads have relatively large file sizes, so we recommend pre-caching as early as possible.
A new ad with the same REWARDED_POPUP_PLACEMENT_ID can be loaded only if the previous ad is closed, not currently displaying and isn’t currently loading. The ideal way is to resolve this is to use the CloseCampaignCallback(string result) method of the callback.
c. Setting up the Callback
Implement Personaly.PopupOfferCallback to receive callbacks from the ad.
public void PrecachePopupOfferCallback(){
// the ad caching is finished and ad ready to show
}
public void ClosePopupOfferCallback(string result){
// the ad is closed
CallbackResult callback = CallbackResult.Create(result);
string placementId = callback.placementId;
}
public void FailurePopupOfferCallback(string result){
// an error occurred while working with ad
CallbackResult callback = CallbackResult.Create(result);
int errorCode = callback.errorCode;
string message = callback.errorMessage;
string placementId = callback.placementId;
}
d. Showing an ad
First, ensure that the ad is loaded in the PrecachePopupOfferCallback (string result) method of the callback.
Use the following code if the ad is loaded and ready to display:
Personaly.ShowRewardablePopup (name, REWARDED_POPUP_PLACEMENT_ID);
Note: You cannot pass anything but the internal property name as the first parameter, otherwise callbacks won’t work.
5. Offer Wall ad
a. Prerequisites
Before you start working with the ad unit, please make sure that the SDK is integrated and initialized as described here.
b. Showing an ad
The OFFER_PLACEMENT_ID key can be found in our dashboard (as placement id) after you define a new ad placement in the Offer Wall tab on the ad settings page.
Use the following code to display an offer wall ad:
Personaly.ShowOfferWall (name, OFFER_WALL_PLACEMENT_ID);Note: You cannot pass anything but the internal property name as the first parameter, otherwise callbacks won’t work.
A new ad with the same OFFER_WALL_PLACEMENT_ID can be loaded only if the previous ad is closed, not currently displaying and isn’t currently loading. The ideal way is to resolve this is to use the CloseCampaignCallback(string result) method of the callback.
c. Setting up the Callback
Implement Personaly.OfferWallCallback to receive callbacks from the ad.
public void CloseOfferWallCallback(string result){
// the ad is closed
CallbackResult callback = CallbackResult.Create(result);
string placementId = callback.placementId;
}
public void FailureOfferWallCallback(string result){
// an error occurred while working with ad
CallbackResult callback = CallbackResult.Create(result);
int errorCode = callback.errorCode;
string message = callback.errorMessage;
string placementId = callback.placementId;
}
6. App Wall ad
Note: the App Wall ad unit is supported only by the Android SDK.
a. Prerequisites
Before you start working with the ad unit, please make sure that the SDK is integrated and initialized as described here.
b. Showing an ad
The APP_WALL_PLACEMENT_ID key can be found in our dashboard (as placement id) after you define a new ad placement in the App Wall tab on the ad settings page.
Use the following code to display an App Wall ad:
Personaly.ShowAppWall (name, APP_WALL_PLACEMENT_ID);Note: You cannot pass anything but the internal property name as the first parameter, otherwise callbacks won’t work.
A new ad with the same APP_WALL_PLACEMENT_ID can be loaded only if the previous ad is closed, not currently displaying and isn’t currently loading. The ideal way is to resolve this is to use the CloseCampaignCallback(string result) method of the callback.
c. Setting up the Callback
Implement Personaly.AppWallCallback to receive callbacks from the ad.
public void CloseAppWallCallback(string result){
// the ad is closed
CallbackResult callback = CallbackResult.Create(result);
string placementId = callback.placementId;
}
public void FailureAppWallCallback(string result){
// an error occurred while working with ad
CallbackResult callback = CallbackResult.Create(result);
int errorCode = callback.errorCode;
string message = callback.errorMessage;
string placementId = callback.placementId;
}
7. Native ad
Native Ads are presented to the users with the same look and feel of the app itself. Native ads provide the classes of the ad (i.e text, creative, tracking etc.) to the publisher, and the publisher takes those classes and inserts them into a design that matches the app’s look.
a. Prerequisites
Before you start working with the ad unit, please make sure that the SDK is integrated and initialized as described here.
b. Implementation
The NATIVE_PLACEMENT_ID key can be found in our dashboard (as placement id) after you define a new ad placement in theNative ad tab on the ad settings page.
Use the following code to pre-cache a Native ad:
// Default method
Personaly.PrecacheNative(name, NATIVE_PLACEMENT_ID);
// 3rd parameter specifies the number of data sets for response
Personaly.PrecacheNative(name, NATIVE_PLACEMENT_ID, 4);
// 3rd parameter responsable for precaching of assets (videos, images)
// 4th parameter can be "video", "image" or null
// 5th parameter specifies the number of data sets for response
Personaly.PrecacheNative(name, NATIVE_PLACEMENT_ID, true, "video", 5);
Note: You cannot pass anything but the internal property name as the first parameter, otherwise callbacks won’t work.
c. Setting up the Callback
Implement Personaly.NativeCallback to receive callbacks from the ad.
public void PrecacheNativeCallback (string result){
// Use the CallbackResult to retrieve the data from the result
CallbackResult callback = CallbackResult.Create(result);
PersonalyNativeAd firstNativeAd = callback.result[0];
}
public void FailureNativeCallback (string result){
// an error occurred while working with ad
CallbackResult callback = CallbackResult.Create(result);
int errorCode = callback.errorCode;
string message = callback.errorMessage;
string placementId = callback.placementId;
}
d. Data set
Dataset objects are represented by the PersonalyNativeAd, PersonalyNativeAdInfo, PersonalyNativeAdAsset classes and the PersonalyNativeAdPrivacyPolicy class. The PersonalyNativeAd class contains common information about the Native Ad, and the PersonalyNativeAdAsset class contains image and video assets.
public class CallbackResult {
public string placementId;
public List<PersonalyNativeAd> result;
}
public class PersonalyNativeAd {
public string impressionId;
public PersonalyNativeAdInfo info;
public List<PersonalyNativeAdAsset> assets;
public string cta;
public string trackingUrl;
public PersonalyNativeAdPrivacyPolicy privacyPolicy;
}
public class PersonalyNativeAdInfo {
public string appName;
public string appId;
public string landingPage;
public string rating;
public string reviews;
public List<string> categories;
public string appDeveloper;
public string appDescription;
public string appIcon;
}
public class PersonalyNativeAdAsset {
public string url;
public string filePath;
public string type;
public float width;
public float height;
}
public class PersonalyNativeAdPrivacyPolicy {
public string url;
public string image;
}
e. Reporing
The publisher is responsible for reporting clicks and impressions. Please use impressionId from PersonalyNativeAd, which can be retrieved from the callback.
CallbackResult callback = CallbackResult.Create(result); PersonalyNativeAd nativeAd = callback.result[0]; string impressionId = nativeAd.impressionId; // Report an impression if the ad with image/video starts showing Personaly.reportNativeImpressionStarted(NATIVE_PLACEMENT_ID, impressionId); // Report an impression if the ad with video showing was finished Personaly.reportNativeImpressionFinished(NATIVE_PLACEMENT_ID, impressionId); // Report click on the Google Play or App Store button Personaly.reportNativeClicked(NATIVE_PLACEMENT_ID, impressionId); #if UNITY_ANDROID // Open Google Play and track the click Personaly.openGooglePlayAndTrackClick (callback.placementId, nativeAd.info.appId, nativeAd.trackingUrl); #endif
8. Custom Server Parameters
The Personaly Unity SDK supports custom parameters for server-to-server callbacks. In order to use them, you should create an object of the class ServerParameter and assign parameter values as follows:
ServerParameter serverParameter = new ServerParameter(); serverParameter.clickId = "CLICK_ID";
At the moment, the Personaly Unity SDK supports one custom server parameter, clickId.
a. Rewarded video/playable ad
Personaly.ShowCampaign (name, REWARDED_PLACEMENT_ID, serverParameter);
b. Interstitial video/playable ad
Personaly.ShowCampaign (name, INTERSTITIAL_PLACEMENT_ID, serverParameter);
c. Rewarded Popup ads
Personaly.ShowRewardablePopup (name, REWARDED_POPUP_PLACEMENT_ID, serverParameter);
d. Native Ads
When you use dataset you should pass custom server parameter when you report click event:
Personaly.reportNativeClicked (NATIVE_PLACEMENT_ID, impressionId, serverParameter);
e. Offer Wall
Personaly.ShowOfferWall (name, OFFER_WALL_PLACEMENT_ID, serverParameter);
In the, Offer Wall the parameter’s value is limited to 32 characters.
9. Mediation
AdMob
a. Prerequisites
The Persona.ly mediation adapter for AdMob supports the following ad units:
- Interstitial
- Rewarded video
b. Integration
- Download our AdMob mediation adapter here.
- Open your project in the Unity editor. Select Assets -> Import Package -> Custom Package and open the PersonalyAdMobAdapter.unitypackage file.
- Make sure that all the files from the list are selected and click on Import.
Android
To setup AdMob mediation, follow the same steps described in the Android integration guide.
iOS
To setup AdMob mediation, follow the same steps described in the iOS integration guide.
- In your Unity project, navigate to Menu -> Edit -> Project Settings -> Player -> iOS Settings -> Target Minimum iOS version and make sure it is set to 8.0 or higher.
- Once you’ve created the Xcode project, drag and drop Personaly.framework to it and navigate to Project Settings -> General -> Embedded Binaries -> Tap + -> Choose Personaly.framework.
- Navigate to Project Settings -> Build Phases ->Tap + -> New Run Script Phase and paste the following snippet into the script text field: bash “${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/Personaly.framework/strip-frameworks.sh” This step is required in order to work around an App Store submission bug when archiving universal binaries.
- Specify the Swift version. Navigate to Project Settings -> Build Settings -> Swift Language Version -> Choose “Swift 4.0”
Please follow these instructions from AdMob in order to complete the setup in AdMob.
MoPub
a. Prerequisites
The Persona.ly mediation adapter for MoPub supports the following ad units:
- Interstitial
- Rewarded video
b. Integration
- Download our MoPub mediation adapter here.
- Open your project in the Unity editor. Select Assets -> Import Package -> Custom Package and open the PersonalyMoPubAdapter.unitypackage file.
- Make sure that all the files from the list are selected and click on Import.
Android
To setup MoPub mediation, follow the same steps described in the Android integration guide here and here.
iOS
To setup MoPub mediation, follow the same steps described in the iOS integration guide here and here
- In your Unity project, navigate to Menu -> Edit -> Project Settings -> Player -> iOS Settings -> Target Minimum iOS version and make sure it is set to 8.0 or higher.
- Once you’ve created the Xcode project, drag and drop Personaly.framework to it and navigate to Project Settings -> General -> Embedded Binaries -> Tap + -> Choose Personaly.framework.
- Navigate to Project Settings -> Build Phases ->Tap + -> New Run Script Phase and paste the following snippet into the script text field: bash “${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/Personaly.framework/strip-frameworks.sh” This step is required in order to work around an App Store submission bug when archiving universal binaries.
- Personaly MoPub adapter uses Swift. Depending on your Xcode project settings you might need to add an Objective C Bridging Header file. Navigate to Project Settings -> Build Settings -> Objective-C Bridging Header -> Add “Libraries/Plugins/iOS/Adapters/MoPub/Bridging-Header.h” (without quotes).
- Specify the Swift version. Navigate to Project Settings -> Build Settings -> Swift Language Version -> Choose “Swift 4.0”
Please follow these instructions from MoPub in order to complete the setup in AdMob.