Skip to content

Android Services

Michalis Kamburelis edited this page Jul 21, 2019 · 2 revisions

Android Project Services Integrated with Castle Game Engine

Android Services

When you use our build tool to package your game for Android, you can easily add services to the project. They allow to comfortably access various Android services (from Google and other 3rd parties, like ad networks) from your Object Pascal game code using the Castle Game Engine.

Table of contents:

Declare project as "integrated"

You need to declare the project type as "integrated" to use any of the services mentioned on this page. Inside the CastleEngineManifest.xml file, add this:

<android project_type="integrated">

Since Castle Game Engine 6.5 it is no longer necessary to specify project_type="integrated", it is the default now. Reasons: almost all real-world applications need the "integrated" type in practice, it allows to include various services, and additional libraries (like FreeType and OpenAL).

Inside the element you will usually add a list, for example like this:

<android project_type="integrated">
    <service name="google_play_services" />
    <service name="google_play_games">
      <parameter key="app_id" value="XXXX" />
    <service name="chartboost" />

The allowed values of project_type are:

  • base: No extra integration, the final project does not use any Java code at all. Rendering and inputs work 100%, since they don't require anything extra, and it may be enough for many games. This is the default in CGE < 6.4.
  • integrated: We include extra Java integration code that allows to use Android project services that communicate with Object Pascal code. This opens the door for the services mentioned below. It also allows to integrate with various native-code libraries (like FreeType and OpenAL). This is the default in CGE >= 6.5.

Immediate benefits of the "integrated" project type

Merely declaring the project type as "integrated" (even without any extra services) immediately gives you:

  • Immersive mode on newer Android devices. This is a "true" full-screen mode for games on Android, where the back/home buttons are usually hidden.
  • You can open URLs (including special market:// URLs to send users to the Google Play store, e.g. to rate your application). Use the OpenURL from CastleOpenDocument unit in Pascal.
  • You can share text and links with other applications. Use ShareText from the CastleOpenDocument unit.
  • You can send Android standard on-screen notification ("toast") using OnScreenNotification from the CastleOpenDocument unit.
  • Some services (like sound and ogg_vorbis) will be added automatically to your project if the sound files are detected in your game data. So merely declaring your project type as "integrated" makes sound work on Android.



Documentation is inside the service directory.


Integration with AppsFlyer.

You need to declare in CastleEngineManifest.xml the "dev key" you have from AppsFlyer, like this:

<service name="apps_flyer">
  <parameter key="dev_key" value="..." />


Enable the Chartboost ads. Use TAds class from the CastleAds unit to show and control the ads from your Pascal code, with AdNetwork set to anChartboost.


  • Using this service requires using also google_play_services.
  • The core of this service is a closed-source library distributed by Chartboost. Download it from , unpack to some temporary location, and copy the lib/chartboost.jar file from the SDK to the castle_game_engine/tools/build-tool/data/android/integrated-services/chartboost/app/libs/ directory.


Integrates your application with Facebook Core SDK.

This integration allows to use Facebook Analytics. Various events are logged automatically (like starting the application or making a purchase). You can also log custom events (only "level achieved" for now) by TFacebook.LogAchievedLevel('level_name') in Pascal (see CastleFacebook unit).

You need to link the application to a Facebook application on :

  • In CastleEngineManifest.xml, you need to specify Facebook Application Id, like this:

    <service name="facebook">
      <parameter key="app_id" value="11223344" />
  • Fill the necessary information in the Facebook application settings. In particular:

    You need to provide to Facebook a "key hash" derived from your application signing keys. See the , section "3. Add Your Development and Release Key Hashes".

    Do also steps mentioned there in "4. Tell Us about Your Android Project".


(Since Castle Game Engine 6.5)

Enable loading the .ttf font files on Android (and other font formats handled by the library).

You can e.g. pass a .ttf file URL to the TTextureFont.Load method. See engine examples like examples/fonts/font_from_texture.lpr to see how to use fonts in CGE.

There is usually no need to include this service explicitly, it is automatically added if your game has "dependency" on "FreeType". Such dependency is in turn automatically detected when the build tool notices a .ttf file inside your data, although it can also be explicitly requested by declaring <dependency name="FreeType" /> in CastleEngineManifest.xml.


Enable the Game Analytics analytics of your apps. Use the TAnalytics class from the CastleAnalytics unit to initialize and send data to the analytics from your Pascal code. Also, all the purchases done using google_in_app_purchases service are automatically send to analytics, with correct price and currency.

  • Using this service requires using also using the google_play_services service.
  • The core of this service is a closed-source library distributed by GameAnalytics. It will be automatically downloaded using the Gradle build system on the first build, so you don't have to do anything.
  • This service requires that you increase the min_sdk_version to 10 or higher in your CastleEngineManifest.xml file. The min_sdk_version is specified at the <android> element.


Enable the Giftiz integration. Your app notifies Giftiz when the user finished a mission inside your game, and Giftiz gives users (real!) gifts. See website for more information, and contact them to get the necessary SDK and partner id.

Use TGiftiz class from the CastleGiftiz unit to control the integration from your Pascal code. Send the "mission complete" message to Giftiz by calling TGiftiz.MissionComplete;. Display Giftiz button on top of your game UI using the TGiftizButton UI service.


  • The core of this service is a closed-source library distributed by Giftiz in their SDK.

    • Unpack the Giftiz SDK to a temporary directory.
    • Copy the GiftizSDKLibrary/libs subdirectory to the castle_game_engine/tools/build-tool/data/android/integrated-services/giftiz/app/libs.
    • Copy the GiftizSDKLibrary/res subdirectory to the castle_game_engine/tools/build-tool/data/android/integrated-services/giftiz/app/src/main/res. Double-check the path: the res goes inside the app/src/main/, while the libs are in higher-level app folder.
    • Copy the button UI images: from GiftizSDK_1.5.0/Customize/Border_white copy the png files to your game's data/giftiz/ subdirectory. There's an alternative set of images in Border_no, and some customization of these images is allowed (see Giftiz SDK for details). Our Pascal integration will automatically load and use these images to display Giftiz button.
  • You need to specify Giftiz partner id for integration. Initially this is TEST_PARTNER_KEY, and if you're accepted --- Giftiz will send you your real partner id. You declare it in your CastleEngineManifest.xml file like this:

    <android project_type="integrated">
        <service name="giftiz">
          <parameter key="partner_key" value="TEST_PARTNER_KEY" />


Enable the Google Analytics analytics of your apps. Use the TAnalytics class from the CastleAnalytics unit to initialize and send data to the analytics from your Pascal code. Also, all the purchases done using google_in_app_purchases service are automatically send to analytics, with correct price and currency.


  • Using this service requires using also the google_play_services service.
  • Recent Google Analytics require you to use a special google-services.json file in your project.
    • On this page click "Get a Configuration File"

    • On a form that appears, add "Analytics" service to your application, selecting proper Google Analytics account parameters.

    • Download google-services.json from the form above.

    • Place the contents of this google-services.json file inside the CastleEngineManifest.xml as the parameter of the google_analytics, like this:

      <service name="google_analytics">
        <parameter key="game_services_json">
        "configuration_version": "1"

Note: You need to create a new "property" in Google Analytics for tracking your mobile application, and obtain a "tracking ID" (like UA-xxx). However, since Google now advices using Firebase for tracking mobile applications, if you click on "Mobile" when creating a new Google Analytics property, it will suggest you to connect your application to Firebase. Instead, create a "Website" property in "Google Analytics" to get a normal tracking ID, and then change the "view" to see mobile application data. See:


This service enables the In-App Purchases through Google Play. The is the most popular way to purchase stuff on Android. Use TInAppPurchases class from the CastleInAppPurchases unit to handle the purchases from your Pascal code.


Enable the Google Play Games Services. Use the TGameService class from the CastleGameService unit in Pascal to initialize and use it, for example to sign-in, send scores and achievements, view achievements and leaderboards, load and save savegames in the cloud.


  • Using this service requires using also google_play_services

  • You must create a project in "Game Services" section of the "Google Developer Console". This will give you a special "app_id" for your project. In order for the integration to work, you need to specify this app_id in our CastleEngineManifest.xml, like this:

    <android project_type="integrated">
        <service name="google_play_services" />
        <service name="google_play_games">
          <parameter key="app_id" value="PASTE-APP-ID-HERE" />

    After this, you need to call from Pascal code GameService.Initialize to connect to Google Play Games when you want (usually, at the beginning of your game: from TCastleApplication.OnInitialize).


This service includes the Google Play Services library into your Android projects. It doesn't provide anything immediately useful, but it's required by some other services, like google_play_games, google_analytics, admob, heyzap.

The necessary files from Google will be automatically downloaded, along with all their dependencies, using the Gradle build system, at the first build. You only have to declare using the service by

<service name="google_play_services" />


Enable the Helpshift, a mobile-friendly support system (submitting issues, chat with support, FAQ). Use the trivial THelpshift class from the CastleHelpshift unit to show the Helpshift activities from your application.


  • Create an account on , to get the necessary keys for your project. Use them when declaring the service parameters in CastleEngineManifest.xml:

    <service name="helpshift">
      <parameter key="api_key" value="xxx" />
      <parameter key="domain" value="" />
      <parameter key="app_id" value="xxx_platform_xxx" />
  • The Helpshift library is automatically downloaded at the first build using Gradle, so you don't have to do anything yourself.

  • Make sure you compile with Android SDK platform 23 or higher (already the default now) and have min_sdk_version >= 14 in your CastleEngineManifest.xml. See the . This page also says you need the target_sdk_version >= 23, but I found that older versions work too.


Enable the Heyzap advertisements. Use TAds class from the CastleAds unit to show and control the ads from your Pascal code, with AdNetwork set to anHeyzap.


  • The core of this service is a closed-source library distributed in Heyzap SDK.
    • Download the SDK from (select in Step 1 whether you want to use beta or not, and then in Step 2. Download the SDK click on SDK link).
    • Unzip the SDK to a temporary location.
    • Copy the jar file from SDK android-sdk/heyzap-ads-sdk.jar into castle_game_engine/tools/build-tool/data/android/integrated-services/heyzap/app/libs/heyzap-ads-sdk.jar.

Optional notes to use Heyzap mediation: You can use Heyzap integration (SDK) to get ads from many ad networks --- not only from Heyzap own network, but also from AdMob, Chartboost and many more. To do this, you will need to setup the integration in your Heyzap dashboard. Also you will need to follow the instructions on to add additional networks SDKs. Select the additional networks on that page, and follow the instructions:

  • Usually, Heyzap docs will instruct you to download some additional SDK. Do as it says, and place the .jar and .aar files into the ..../integrated-services/heyzap/app/libs/ directory, alongside the Heyzap jar.

  • For every .aar file that you have added, add appropriate <dependency> line to the ..../integrated-services/heyzap/app/build.gradle file. Like this:

    <dependency>compile(name:'AudienceNetwork', ext:'aar')</dependency>
    <dependency>compile(name:'unity-ads', ext:'aar')</dependency>
  • Make the necessary modifications in the ..../integrated-services/heyzap/app/src/main/AndroidManifest.xml. Make sure it contains only (and exactly!) the activities/permissions that Heyzap docs show you.

  • Note for AdMob: Using AdMob requires that you also use "google_play_services" service. And you should add to the ..../integrated-services/heyzap/app/build.gradle file these lines:

    <dependency>compile ''</dependency>
    <dependency>compile ''</dependency>
  • Note: that some ads SDK may require increasing the min_sdk_version in your CastleEngineManifest.xml. You will get a clear error message when building APK in case this is necessary. Currently, Facebook Ads (Facebook Audience Network) requires min SDK >= 11.

  • Note: when you use Heyzap to integrate with some 3rd-party ad network (for example with Chartboost), then you should not add a service in CastleEngineManifest.xml to also directly interact with this network (in this example "chartboost"). That is: include only the heyzap service in CastleEngineManifest.xml. Otherwise the SDK underneath (like chartboost) will be initialized and handled by two code paths (one directly in our Java code, and one inside Heyzap jar), which can lead to various troubles.

  • To test your integration, call TAds.StartTestActivity(anHeyzap) in your Pascal code. This will show a special activity where you can test whether the connection with your 3rd-party networks works OK. Optional, but highly suggested!


Enable the sound service on Android. There is no need to include this service explicitly, it is automatically added if your game depends on a sound library. Which in turn may be done by declaring <dependency name="Sound" /> in CastleEngineManifest.xml, but usually it's automatically detected when the build tool notices a sound file inside your data.


Enable the StartApp ads. Use TAds class from the CastleAds unit to show and control the ads from your Pascal code, with AdNetwork set to anStartApp.


Enable the OggVorbis sound format on Android.

There is no need to include this service explicitly, it is automatically added if your game depends on "OggVorbis". Which in turn is automatically detected when the build tool notices an .ogg file inside your data, although it can also be explicitly requested by declaring <dependency name="OggVorbis" /> in CastleEngineManifest.xml.

In effect, loading OggVorbis sound files in your Android games just works -- you only need to make sure your Android project_type is set to "integrated".

We use very fast open-source OggVorbis implementation called Tremolo, see . You can compile Tremolo in low-precision mode ( to get more efficiency (decoding will be faster, less CPU hungry), although then the quality is quite horrible in my tests.

Note that on Android, the sound engine (with OpenAL underneath) has to be paused / resumed when user switches between applications. If you play some music, and you want resuming to start it again --- you need to register you callback on SoundEngine.OnOpenClose to handle this situation. If you play music using TMusicPlayer, this is taken care of automatically.


Operations with native picture gallery.

Use the Pascal class TPhotoService (use CastlePhotoService unit) to store your image into Pictures folder in the system gallery. Using this service automatically adds the WRITE_EXTERNAL_STORAGE permission.


Allows to vibrate the device. Use the Vibrate procedure from CastleOpenDocument unit to cause vibration from Object Pascal code.

It's easy to add more services!

It's very easy to add your own Android services, if you need to integrate with some Android library not covered above. Simply create your service inside the castle_game_engine/tools/build-tool/data/android/integrated-services/xxx/ directory. The files there are copied to the final Android project, expanding macros inside. Most of the files are simply copied (but without overwriting), but some files are merged in a special way:

  • AndroidManifest.xml of each service is merged with the main AndroidManifest.xml in a smart way, only adding the new permissions and new elements/attributes inside the .

  • build.gradle files inside the services have a special XML syntax. See the example services like helpshift. They are merged into the final (non-XML) build.gradle file in a smart way.

  • Each service may also insert a snippet of Java code to the file. This is typically used to initialize the service-specific Java class, like

    services.add(new ServiceStartApp(this));

When developing new services, it's useful to inspect the generated Android project in the castle-engine-output/android/project. This is created by the Build Tool by merging all the services with base project template.

To communicate with the services from the Object Pascal code, use the CastleMessaging unit. Our units like CastleAds or CastleGameService are simply thin "wrappers" using CastleMessaging unit under the hood --- see at their sources to know how it works! A detailed explanation is also available in this forum post: .

Clone this wiki locally
You can’t perform that action at this time.