Last Edited: January 27th, 2020.
A few weeks ago we hosted a Live-Webinar "How to Integrate Appodeal SDK in Unity Effortlessly". For those of you that are interested in monetizing your latest Unity mobile games with Appodeal, or want to solve any questions & doubts regarding that matter, here you have the full Video Guide!
Introduction to this Video-Guide
This webinar was hosted by Dmitry Feschenko, one of the awesome Technical Support Engineers at Appodeal, and it will be broadcasted in English and Russian languages. The Zoom webinar was open & free to anyone interested from all over the world, and we covered the following topics:
- All you need to know to integrate the Appodeal SDK into your Unity Projects.
- Android & iOS building process for various Unity versions.
- Useful tech tips when monetizing with Unity.
- And much more!!!
At the end of the webinar, all participants were able to submit any questions for a short live Q&A (Question & Answer) session with Dmitry.
This webinar was originally recorded in Russian and has been dubbed into English.
You can also download here the Test Project from this video.
Learn step-by-step how the Appodeal SDK integration works in the Unity platform, from one of our tech experts in Appodeal!
Video Guide Transcription
Hi everyone, my name is Dmitry. I've been working as a Technical Support Specialist in Appodeal for two years, and today we're having a webinar on the principles of integrating the Appodeal SDK into Unity projects.
Before we start, there are several things I'd like to note. First, the integration process we're going to describe today applies to the current Apple dls decay versions, and works for unity 2017.4 to 2020. The processes may change in the future so I would recommend always checking with the documentation and following whatever it says. If you have any questions throughout the webinar, ask them in the chat right away, and don't forget to provide your contact details. We will allocate some time to answer them at the end of the webinar. If we don't manage to answer a question today, we will prepare a written response and send it to a mail, or hold a new webinar on that topic.
Let's start with integrating Appodeal SDK into the project. I will be using unity 2020.1.16 installed through the Unity hub however the procedure is the same for all supported unity versions let's go to the projects tab and create a new project. Let's name it Appodeal Webinar.
Our plugin is available on Unity Asset Store but I recommend using the unity package file from our documentation because it always has the latest version of our plugin. Whereas uploading updates to the asset store may take some time. Let's wait for the project to be created and continue.
Great! Now let's click on assets > import package > custom package > and provide the path to the file we have downloaded from the documentation. Please note that I'm using Aperture plugin version 2.11.2. Let's click, open in this window. We can see the content of our plugin. Most of the files are scripts are wrappings for native Android and iOS SDK methods. The plugin also includes Appodeal demo scene and the script to manage it here in the network configs folder we're going to have all dependencies for all ad networks included in our plugin.
Finally our SDK includes a third-party external dependencies manager plugin designed for resolving dependency conflicts automatic project setup and so on let's keep all the files selected by default and click import to add these files to the project.
Great! Before we start with project setup for Android and iOS, let's take a quick look at the content of our plugin. Appodeal demo scene is located at assets > Appodeal demo scenes. Let's load it and as you can see here we have two groups of buttons one for checking to add SDK logic and the other one for checking the work of the consent manager let's restore default settings
We also have Appodeal demo script connected to the canvas so we will see how it works later on.
When you create an app in Appodeal you provide its bundle identifier also called package name and we generate a unique app key if you decide to use the demo project for testing ads in your app you will need to replace the Android or iOS app key in this script with respective keys for your app the last thing I'm going to tell you about in this section is how callbacks work on unity we have a separate article on that in our documentation.
In our SDK callbacks work in the main Android and iOS threads, not the main unity thread that's why if you try to manage changes to the UI within these methods the app may freeze the article provides several ways of dealing with this issue so everyone can find a suitable solution
Now let's go to the project setup for Android I'd like to remind you that I'm using the 2020.1 version but the process shown here is identical for all versions starting from unity 2019.3.7 let's go to the player tab of the project settings window and select Android platform
In other settings you will need to choose the project package name. I will be using the default one "com.appodeal.test". You should also set the minimum API level to 21 or higher and set scripting backhand to il2cpp now we're done with the project settings so let's go-to publishing settings here we need to check several options custom main manifest custom main Gradle template, Custom base, Gradle template, and custom Gradle properties template.
Once we've done that, respective files have been created and placed in assets plugins Android. Now, we're going to set them up. Let's start with the Android Manifest file. We're also going to need "androidmanifest.xml" located in the Appodeal folder. Let's open both of these files.
Starting with the 2019.4 version of Unity, our androidmanifest.xml file is no longer used during the build. So, we will have to manually add the permissions needed for the work of our SDK, to the main manifest file, by simply pasting them under the manifest tag.
Great! Now our next move will be adding the AdMob app ID under the application tag. If we skip this step, the app will be crashing at launch, because app ID is required by Admob SDK.
This ID has to be pasted under the application tag. Also, note that you will need to replace the ID with the respective ID from your AdMob account. Let's save and close the file.
Now let's open the base project and plate Gradle file and check the Gradle version in our case we need to change it to 3.6.4 in accordance with the new Android requirements for os version 11. you only need to do this if your target API level is 30. You can find more about this tab in our documentation.
Okay! We're done. Let's save and close the file. We're not going to need it anymore. Now let's open the two remaining files. Gradle template and main template. We won't be editing them, for now. They will be adjusted automatically during the resolve and we're just going to observe the results.
Now let's go to Android Resolver > settings > assets > external dependency manager > Android resolver > settings. We need to make sure that all the settings have default values, just the way I have them here. You also need to check the use Jetify function.
Jetify replaces classical Android dependencies with their Android x counterparts. Let's press ok now let's go to build settings file build settings add the Apple deal demo scene to the project.
And switch the platform to Android.
I'd like to say that multi-x is natively supported starting from minimum API level 21 so you don't need to enable it separately. Let's wait for the assets to reload.
Android resolver window will appear. Let us click enable to activate automatic dependency conflict resolution.
Done! Now let's look at our file. As you can see Gradle template properties file now has the strings required for using Android x libraries.
The main template Gradle file has been edited as well. It now includes all dependencies from our SDK as well as some other information.
One more thing to note is that the resulting manifest file generated during the build will contain more permissions because some of them are going to be added from ad network manifests and be required for their work.
Now, I'm going to open the terminal and run an emulator to show you the demo.
Let's start the project build by pressing build and run let's create a folder named Android build, and name our file "debug".
While the app is building I'm going to briefly tell you about using our plugin method for integrating Appodeal SDK into your projects: For the work of callback methods, allowing to see the state of an ad creative, loaded or not, shown or not, watched till the end or not, etc.
You need to inherit your class from the respective class. All possible options are listed here: the start function initializes consent manager awake function uses SDK method to display consent request window. Android versions up to and including version 6.
In the "on destroy" function we implemented banner view destruction when switching to a different scene to free up resources. Request consent info update method sends a request to our server to know if consent window needs to be shown to a specific user. "Setcustomvendor" function has a code for adding a vendor to the consent window vendor list. The next three functions display information on whether or not the consent window needs to be shown to the user, whether or not the user is within the geographical scope of GDPR or CCPA, and the current consent status.
Load consent form function loads the content of concerned window.
The next function provides information about the form loading status. Who form as activity and show form as dialogue functions allow displaying the loaded form as an activity or a dialogue window.
The two remaining functions that have to do with the consent manager show the consent string in IAB format, and main information about the current consent status for the bug let's stop here for now and get back to the code at the next opportunity.
Let's wait for the build to complete and take a quick look at our demo project. As you can see the project has been built and we're now going to our emulator.
Now let me show you how consent manager works first let's request consent status from our server force load the form. Wait for the form to load then show it… and agree to the terms.
Well, looks like the app froze a bit… oh now it's working again!
Now let's turn our attention to Appodeal logic. I'm going to turn on the test mode and initialize the SDK. I will also start caching an interstitial and show a banner. For now, the banner works fine, so let's hide it and show an interstitial. Everything works fine
Let's close the emulator.
Now, let's get back to our project and set it up for iOS platform. Let's open player in project settings and go to the iOS tab here. We're also going to need to go to other settings. First of all, let's replace the project bundle identifier with yours. In my case, it's com.appodeal.testing.
The next thing I'm going to do has to be done because I'll be running our SDK using an emulator. You don't have to do it when you're building for an actual device. I'm going to turn off auto graphics API and add open glass. I'm also switching target SDK from device SDK to simulator SDK.
Okay so now we're done setting up our project for iOS. As you see it's easier than setting up for Android. Now let's go to build settings and change the platform to iOS.
Please, make sure you have the latest versions of Coco pods and XCode for the current version of iOS. upper dlsdk the minimum supported versions are Coco pods 1.9 and XCode 12.
Good! Now let's start building and name the folder.
Now let's get back to the plugin code a detailed description of these methods is provided in our documentation. And for now, I'm only going to tell you about the most important ones:
Set testing method allows turning our SDK test mode on or off. Set log level method determines which information will be shown in the console. Set auto cache method determines the add caching mode manual or automatic.
Please, note that in this script we turned off auto caching for interstitials and rewarded videos.
Next, come the methods that initialize callback methods and show the use of custom filters for user segmentation purposes.
Let's stop here and wait for the project to export.
Okay! Now let's open the project we've created and check if it has .xc workspace file. That we'll be using later on.
If you don't have this file you need to open the pod file located in the same folder and check if it contains the dependencies for our SDK. For that you will need to: go back one directory. Open the terminal and execute the part. Install command. If the command is executed successfully our xc workspace file will be generated and all dependencies needed for the work of our SDK will be downloaded.
If you have any errors at this stage, which typically happens when some of the tools needed for the process are missing, the easiest option I would recommend is contacting our support, and sending us the full error log from the console, and we'll help you fix it as fast as we can.
Now let us edit the info list file.
Please, note that it is in the project root folder. We will need to add a more web ID, just like we did with Android. Let's save and close the file then open the .xc workspace file.
Let's choose an emulator. I'll be using iPhone 12 and start building the app while the project is building. Let us take a final look at our script.
Following methods are used to show up Appodeal.
Let us start with interstitials. As you can see, first comes the can show check it includes checking if the ad creative has been loaded and if ads can be shown in a given placement.
This method can be executed with one or two parameters indicated. The second one is a string with a respective placement name.
The next check is precache, which checks if the loaded creative is pre-cache or a regular ad. Precache is loaded as fast as possible a tap launch, but is typically less expensive than a regular ad. If the conditions are met, we show the ad using the show method. As I said previously, we turned off automatic caching for interstitials and rewarded videos so, in these cases, we have to use cache method at any time we want to load an ad the procedure. Is the same for rewarded videos banners, and brack don't need these checks due to their peculiarities so whenever a creative is loaded it is shown automatically if "show method" was called previously.
As you can see, we can use predefined positions, such as banner bottom or banner left. But you can also show ads in any other part of the screen according to your taste.
Finally, below you can see the callbacks that you can use to manage how ads are shown in your project.
So that's the end of our script. Let's close it.
The project has already been built, so let us wait until it is launched on the simulator.
Let's check the work of consent manager and ad logic, just like we did with Android- Let's request the consent status load the form, and show it.
Let's agree and check the add logic again. We're turning on the test mode so we don't have to wait for the actual creative to load.
Looks like I made a mistake when providing the bundle identifier so the ad doesn't show.
Anyway, if you provide the valid bundle identifier and app key you won't be having this problem.
With that, we've finished with the app.
Round of Questions from the Viewers
Let us see if we have any questions. If you haven't asked them so far now is the time. We will give an answer to all of them.
The first question: why are there so many errors and anrs because of Appodeal? Appodeal is a mediation service that includes many ad networks all of which are rather complex products as you know mobile device market offers a lot of models from different manufacturers based on different hardware so avoiding errors completely is simply not possible whenever a new os update is rolled out users experience errors and that is completely normal we keep tracking errors in our SDK and the SDKs of our partners and we also regularly update our SDK and add network as the case that it contains
What emulator are you using? For Android, I'm using a standard emulator from Android studio.
I've been using your plugin for a year and whenever I made an app build for google I had a lot of areas that took one or two days to resolve. Your documentation describes a completely different way of building, not the one you showed during the webinar.
Thanks a lot for your question, Alexander. That's true, our documentation shows a slightly different integration method the reason is that Appodeal supports different unity versions starting from 2017.4. For each of these versions, the integration process is a bit different so we have to include extra integration steps for users running different unity versions. The method I have shown during the webinar is valid for unity versions starting from 2019.3.7 so you can use it and there won't be any errors.
Now I have a question in English: note that I send some questions to the webinar Appodeal.com email. Thanks a lot for mentioning that, we will check our inbox after the webinar prepare the answers, and send them to your email.
The next question also in English: do I have to be on mac to build for android? Thank you for your question. No, you don't have to be on mac to build for Android, you can do it on windows without any problems.
One more question, in English: Can we have a test demo of this webinar? Sure, I will upload the Test Project to the cloud, and we will post the link together with the video on our official Appodeal youtube channel.
One more question in English: kindly give us more demo on user consent on GDPR? as you know, GDPR and the recently adopted CCPA apply to the EU and California respectively. According to these legal acts, you, as the developer, have to ask for user consent before collecting any information from them. Our consent manager was developed exactly for this purpose so you don't have to come up with a solution on your own. Documentation on the manager is in the open-access Appodeal documentation, so go ahead, integrate the consent manager, and ask for user consent. One more thing, I'd like to add is that since those laws only apply to the EU and the USA, you don't have to show this window to users from other regions.
Can internet shutdowns in Belarus affect up Appodeal server? Thank you for your question. Our servers are not located in Belarus, so the shutdowns will not affect them in any way.
The next question is in English: for the non-EU region, shall we send false boo value to the consent manager? No, for the non-EU region you can set it to true by default. You don't have to show the consent window as I mentioned previously.
Hi, how do I remove Fungal add network from the SDK? Hi, Anton thank you for your question. In the latest versions of our SDK it's very easy. In fact, there are several ways of doing so, as I said at the beginning of the webinar. Our SDK has a network configs folder with .XML files in it. You can simply delete the file belonging to a certain ad network and this will be enough for it to be removed from your SDK after the resolve.
Why are all ad types shown using a single script? why not have a separate one for each ad type? Thank you for your question, the thing is that this project is designed for our users to learn about the work of our SDK, so it's not a perfect option ready for production. For your own purposes, you can use as many individual scripts as you need.
Why are there no comments in the code explaining what happens in a certain string? Thanks in advance. The thing is our documentation available at the Appodeal website is quite detailed, providing the exact explanation of how which method works why you need them, and what you can do with their help. If you're still unable to find the answers to any of the questions you may have you can always contact our support by emailing us at support appodeal.com or via live chat at our website. We'll be happy to tell you more about what this or that method does.
What if the user does not give consent? are there any statistics on consent? Of course! If the user does not consent to have their personal data processed, the ads will still be shown in the app. It's just that they won't be targeted because neither ourselves nor the SDKs of our partners that we have in our SDK will be collecting any data on that user.
Of course, there are statistics in consent. but I wouldn't talk about them right now, as this varies greatly depending on the details. Like show location, for example, in the US users, are more critical about sharing their personal data, so the share of concerns given will be smaller than in some other regions. I hope this answers your question
Let's wait for a couple more minutes. Please, ask your questions if you still have any.
The first question in Russian: when adding Appodeal and Google Play Services like achievements and such, the project starts getting errors with dependency conflicts, so I had to build the project using Android Studio. Can I resolve these errors in the new version of unity, so I don't have to use Android Studio? Yes, sure you can do that in the current unity version. As far as I can remember, there are some errors that appeared after the release of the 2019.3 version, and were only fixed in version 2019.3.7. At the moment there are no problems so you can do it. If you fail to complete it on your own, following the steps from our webinar, please come to our support we'll be glad to help you out.
I have noticed that Appodeal documentation in the Russian version of your website is missing some of the footnotes with the code. However, they are available in the English version. Why is that? Thank you for your question, Artom. This can happen when the translation plugin fails to add this information. Could you please specify what documentation exactly you mean? if it's Unity or Android, we will check this right away, and fix it as soon as possible.
Okay, no more questions!
Finally, I'd like to say it again. Don't hesitate to contact our support from your Appodeal Dashboard, with any questions that you may have. This will most probably help you resolve any difficulties, much faster than you would, acting on your own.
Also, please pay attention to the documentation. Whatever it says, must be done unless otherwise specified.
I'd like to thank everyone for participating in today's webinar. Have a nice day and enjoy the upcoming holidays. Bye-bye!
<!--[if lte IE 8]><![endif]-->
