Android Services | Manual | Castle Game Engine

Android Services

Table of Contents

1. Introduction
2. List of Services
- 2.1. Past (removed) services
3. How it works
4. Default features of integrated projects
5. Adding new services

1. Introduction

When you 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.

The Android services are declared in CastleEngineManifest.xml like this:

<android>
  <services>
    <service name="google_play_services" />
    <service name="google_in_app_purchases" />
  </services>
</android>

2. List of Services

Services useful to add to the project explicitly (by adding them to the CastleEngineManifest.xml file):

Services that are added automatically under certain conditions (you usually don’t need to know about them):

freetype (added automatically if we detect font files, like .ttf or .otf, in your data directory)
ogg_vorbis (added automatically if we detect OggVorbis (.ogg) files in your data directory)
png (added automatically if we detect PNG files in your data directory)
sound (added automatically if we detect sound files (.ogg, .wav) in your data directory)

2.1. Past (removed) services

The Android ecosystem is dynamic, and some products just disappear and/or are replaced by something very different over time. As such, some of our past services are no longer available:

Giftiz: Service no longer available, as the company developing it (and maintaining the server) is no longer available.
Heyzap: Service no longer available. The company behind it was acquired by Fyber. Which was later acquired by Digital Turbine. Perhaps the SDK from Digital Turbine can offer similar functionality, but we didn’t test it yet.

Google Analytics: It has been deprecated by Google and, while it still compiles, it crashes on new devices:

 FATAL EXCEPTION: main
Process: net.sourceforge.castleengine.dragonsquash, PID: 19322
java.lang.IllegalArgumentException: net.sourceforge.castleengine.dragonsquash: Targeting S+ (version 31 and above) requires that one of FLAG_IMMUTABLE or FLAG_MUTABLE be specified when creating a PendingIntent.
Strongly consider using FLAG_IMMUTABLE, only use FLAG_MUTABLE if some functionality depends on the PendingIntent being mutable, e.g. if it needs to be used with inline replies or bubbles.
        at android.app.PendingIntent.checkFlags(PendingIntent.java:378)
        at android.app.PendingIntent.getBroadcastAsUser(PendingIntent.java:648)
        at android.app.PendingIntent.getBroadcast(PendingIntent.java:635)
  ...
        at com.google.android.gms.analytics.GoogleAnalytics.getInstance(Unknown Source:15)
        at net.sourceforge.castleengine.ServiceGoogleAnalytics.getAppTracker(ServiceGoogleAnalytics.java:58)
  ...

Google recommends to migrate to their Firebase SDK. Not implemented in CGE yet (but may be in the future).

Currently the best mobile analytics, integrated with CGE on both Android and iOS, are provided by game_analytics service.

3. How it works

While the base Castle Game Engine activity on Android uses NativeActivity, we add Java code to integrate with additional services you request.

The build tool will automatically create Android project that contains all the necessary services, and it will invoke Android tools to build and run it.

4. Default features of integrated projects

Even if you don’t add any services explicitly, by default the following features are available:

Immersive mode. This is a "true" full-screen mode for games on Android, where the back/home buttons are usually hidden.
You can open URLs in external applications using OpenUrl.

Note
Open special market:// URL on Android to send users to the Google Play store, e.g. to rate your application.
You can share text and links with other applications using ShareText. This allows to e.g. propose users to send a message with a link to your game to their friends.
You can send Android standard on-screen notification ("toast") using OnScreenNotification.
Some services (like sound and ogg_vorbis) will be added automatically to your project if the sound files are detected in your game data.

5. Adding new services

See Adding New Android Services.

Take a look at the end of Pascal Cafe 2024 Slides for a short overview explaining how are Android and iOS projects build and how the services are added.

To improve this documentation just edit this page and create a pull request to cge-www repository.