The iOS Screenshot/Splash Screen Process

iOS apps seem to start almost instantly in comparison to Android apps.
There is a trick to that, iOS applications have a file traditionally called Default.png that includes a 320x480 pixel image of the first screen of the application. This creates an "illusion" of the application instantly coming to life and filling up with data, this is rather clever but is a source trouble as the platform grows [1].

You can disable the screenshot process entirely with the ios.fastBuild=true build hint. This will only apply for debug builds so you don’t need to worry about accidentally forgetting it in production.

The screenshot process was a pretty clever workaround but as Apple introduced the retina display 640x960 it required a higher resolution [email protected] file, then it added the iPad, iPad Retina and iPhone 5 [2] iPhone 6 & 6+ all of which required images of their own.

To make matters worse iPad apps (and iPhone 6+ apps) can be launched in landscape mode so that’s two more resolutions for the horizontal orientation iPad. Overall as of this writing (or until Apple adds more resolutions) we need 10 screenshots for a typical iOS app:

Table 1. iOS Device Screenshot Resolutions
Resolution File Name Devices

320x480

Default.png

iPhone 3gs

640x960

[email protected]

iPhone 4x

640x1136

[email protected]

iPhone 5x

1024x768

Default-Portrait.png

Non-retina ipads in portrait mode

768x1024

Default-Landscape.png

Non-retina ipads in landscape mode

2048x1536

[email protected]

Retina ipads in portrait mode

1536x2048

[email protected]

Retina ipads in landscape mode

750x1334

[email protected]

iPhone 6

1242x2208

[email protected]

iPhone 6 Plus Portrait

2208x1242

[email protected]

iPhone 6 Plus Landscape

You can predefine any of these files within the native/ios directory in your project. If the build server sees a file matching that exact name it will not generate a screenshot for that resolution

Native iOS developers literally run their applications 10 times with blank data to grab these screenshots every time they change something in the first view of their application!

With Codename One this will not be feasible since the fonts and behavior might not match the device. Thus Codename One runs the application 10 times in the build servers, grabs the right sized screenshots in the simulator and then builds the app!

This means the process of the iPhone splash screen is almost seamless to the developer, however like every abstraction this too leaks.

The biggest problem developers have with this approach is for apps that use a web browser or native maps in the first screen of their app. This won’t work well as those are native widgets. They will look different during the screenshot process.

Another problem is with applications that require a connection immediately on startup, this can fail for the build process.

A solution to both problems is to create a special case for the first launch of the app where no data exists. This will setup the screenshot process correctly and let you proceed with the app as usual.

Size

One of the first things we ran into when building one of our demos was a case where an app that wasn’t very big in terms of functionality took up 30mb!

After inspecting the app we discovered that the iPad retina PNG files were close to 5mb in size…​
Since we had 2 of them (landscape and portrait) this was the main problem.

The iPad retina is a 2048x1536 device and with the leather theme the PNG images are almost impossible to compress because of the richness of details within that theme. This produced the huge screenshots that ballooned the application.

Mutable first screen

A very common use case is to have an application that pops up a login dialog on first run. This doesn’t work well since the server takes a picture of the login screen and the login screen will appear briefly for future loads and will never appear again.

Unsupported component

One of the biggest obstacles is with heavyweight components, e.g. if you use a browser or maps on the first screen of the app you will see a partially loaded/distorted MapComponent and the native webkit browser obviously can’t be rendered properly by our servers.

The workaround for such issues is to have a splash screen that doesn’t include any of the above. Its OK to show it for a very brief amount of time since the screenshot process is pretty fast.

Local Notifications on iOS and Android

Local notifications are similar to push notifications, except that they are initiated locally by the app, rather than remotely. They are useful for communicating information to the user while the app is running in the background, since they manifest themselves as pop-up notifications on supported devices.

Sending Notifications

The process for sending a notification is:

  1. Create a LocalNotification object with the information you want to send in the notification.

  2. Pass the object to Display.scheduleLocalNotification().

Notifications can either be set up as one-time only or as repeating.

Example Sending Notification
LocalNotification n = new LocalNotification();
n.setId("demo-notification");
n.setAlertBody("It's time to take a break and look at me");
n.setAlertTitle("Break Time!");
n.setAlertSound("beep-01a.mp3");

Display.getInstance().scheduleLocalNotification(
        n,
        System.currentTimeMillis() + 10 * 1000, // fire date/time
        LocalNotification.REPEAT_MINUTE  // Whether to repeat and what frequency
);

The resulting notification will look like

Resulting notification in iOS
Figure 1. Resulting notification in iOS

Receiving Notifications

The API for receiving/handling local notifications is also similar to push. Your application’s main lifecycle class needs to implement the com.codename1.notifications.LocalNotificationCallback interface which includes a single method:

public void localNotificationReceived(String notificationId)

The notificationId parameter will match the id value of the notification as set using LocalNotification.setId().

Example Receiving Notification
public class BackgroundLocationDemo implements LocalNotificationCallback {
    //...

    public void init(Object context) {
        //...
    }

    public void start() {
        //...

    }

    public void stop() {
        //...
    }

    public void destroy() {
        //...
    }

    public void localNotificationReceived(String notificationId) {
        System.out.println("Received local notification "+notificationId);
    }
}
localNotificationReceived() is only called when the user responds to the notification by tapping on the alert. If the user doesn’t click on the notification, then this event handler will never be fired.

Canceling Notifications

Repeating notifications will continue until they are canceled by the app. You can cancel a single notification by calling:

Display.getInstance().cancelLocalNotification(notificationId);

Where notificationId is the string id that was set for the notification using LocalNotification.setId().

Push Notifications

Push notification allows us to send a notification to a device while the application might be in the background. This is important both as a marketing tool and as a basic communications device.

Why Push & Not Polling?

Polling the server or long polling seem like sensible time proven strategies. However, there are many complexities related to that strategy in mobile phones.

The biggest problem is that a polling application will be killed by the OS as it is sent to the background to conserve OS resources. While this might work in some OS’s and some cases this isn’t something you can rely on. E.g. Android 6+ tightened the background process behavior significantly.

The other issue is battery life, new OS’s expose battery wasting applications and as a result might trigger uninstalls. This makes even foreground polling less appealing.

The final issue is networking, polling is problematic when a device is connected via cellular connection and switching towers. Push might have issues as well, but it’s hard to beat the QA/optimization done by Apple/Google.

What Is Push?

If you are new to mobile development then you heard a lot of buzzwords and very little substance. The problem is that iOS and Android have very different ideas of what push is and should be.

For Android push is a communication system that the server can initiate. E.g. the cloud can send any packet of data and the device can process it in rather elaborate ways.

For iOS push is mostly a visual notification triggered by the server to draw attention to new information inside an app.

These don’t sound very different until you realize that in Android you can send/receive a push without the awareness of the end user. In iOS a push notification is displayed to the user, but the app might be unaware of it!

iOS will only deliver the push notification to the app, if it is running or if the user clicked the push notification popup!

Codename One tried to make both OS’s "feel" similar so background push calls act the same in iOS and Android as a result.

You shouldn’t push important data, push is lossy and shouldn’t include a payload that MUST arrive!
Instead use push as a flag to indicate that the server has additional data for the app to fetch

The Push Bureaucracy - Android

Android Push goes thru Google servers and to do that we need to register with Google to get keys for server usage.

We need two important values: GCM_SENDER_ID & GCM_SERVER_API_KEY. The former is used in the client and the latter value is used to push from the server code.

To generate these values we need a Google cloud project. We go over the process of generating a cloud project in the Google+ login section here.

To generate those just go to https://developers.google.com/mobile/add and click pick a platform:

Click
Figure 2. Click "pick a platform"

Select Android App

Select
Figure 3. Select "Android App"
Google introduced support for sending GCM messages to iOS applications, this has nothing to do with the iOS native push we discuss below

Enter the details for the app and the package

Enter the details for the app and the package
Figure 4. Enter the details for the app and the package

Click the Cloud Messaging option then click the Enable Google Cloud Messaging button

Click the
Figure 5. Click the "Cloud Messaging" option then click the "Enable Google Cloud Messaging" button

You should now have the values for both GCM_SENDER_ID & GCM_SERVER_API_KEY as illustrated below. Notice that the sender id is the numeric key whereas the api key is the alpha-numeric key:

You should now have the values for both `GCM_SENDER_ID` & `GCM_SERVER_API_KEY`
Figure 6. You should now have the values for both GCM_SENDER_ID & GCM_SERVER_API_KEY

The Push Bureaucracy - iOS

Push on iOS is much harder to handle than the Android version, however we simplified this significantly with the certificate wizard.

iOS push needs two additional P12 certificates.

Please notice that these are NOT the signing certificates!
They are completely different certificates that have nothing to do with the build process!

The certificate wizard can generate these additional push certificates and do quite a few other things if you just check this flag in the end of the wizard:

Enable Push in the certificate wizard
Figure 7. Enable Push in the certificate wizard
If you already have signing certificated defined for your app just skip the certificate generation phase (answer no) the rest will work as usual.

You can then install the push certificates locally and use them later on but there is an easier way.

You need to host the push certificates in the cloud so they will be reachable by the push servers, Codename One that for you seamlessly.
Once you go thru the wizard you should get an automated email containing information about push and the location of the push certificates, it should start like this:

iOS Push certificates have been created for your app with bundle ID com.mycompany.myapp.mypushdemo.  Please file this email away for safe keeping as you will need the details about the certificate locations and passwords to use Push successfully in your apps.

Development Push Certificate URL:
https://codename-one-push-certificates.s3.amazonaws.com/com.mycompany.myapp.mypushdemo_DevelopmentPush_LONG_UNIQUE_KEY.p12

Development Push Certificate Password: ssDfdsfer324

Production Push Certificate URL:
https://codename-one-push-certificates.s3.amazonaws.com/com.mycompany.myapp.mypushdemo_ProductionPush_LONG_UNIQUE_KEY.p12

Production Push Certificate Password: ssDfdsfer324

The URL’s and passwords are everything that you will need later on to get push working on iOS. Notice that the wizard also performs a couple of other tasks specifically it sets the ios.includePush build hint to true & adds push to the provisioning profile etc.

You can read more about the certificate wizard in the signing section.

Push Client Code

Push has two distinct pieces, the device that receives the push notification (the client) and the code that sends the push notification (either another device or more often the server code).

The following code shows a simple push test client application, we go over the significant pieces below:

public class PushDemo implements PushCallback { (1)
    private Form current;
    private Resources theme;

    private static final String MY_SERVER_URL = "https://.../"; (2)
    private static final String GCM_SENDER_ID = "99999999999999";  (3)

    public void init(Object context) {
        theme = UIManager.initFirstTheme("/theme");
    }

    public void start() {
        if(current != null){
            current.show();
            return;
        }
        Form hi = new Form("Push Test");
        Display.getInstance().callSerially(() -> {  (4)
            Hashtable metaData = new Hashtable();
            metaData.put(com.codename1.push.Push.GOOGLE_PUSH_KEY, GCM_SENDER_ID);
            Display.getInstance().registerPush(metaData, true);
        });
        hi.show();
    }

    public void stop() {
        current = Display.getInstance().getCurrent();
        if(current instanceof Dialog) {
            ((Dialog)current).dispose();
            current = Display.getInstance().getCurrent();
        }
    }

    public void destroy() {
    }

    @Override
    public void push(String value) {
        Dialog.show("Received Push", value, "OK", null);  (5)
    }

    @Override
    public void registeredForPush(String deviceId) {
        // IMPORTANT: Notice that Push.getPushKey() != deviceId !!!
        ConnectionRequest con = new ConnectionRequest(MY_SERVER_URL, true);  (6)
        con.addArgument("pushKey", Push.getPushKey());
        NetworkManager.getInstance().addToQueue(con);
    }

    @Override
    public void pushRegistrationError(String error, int errorCode) {
        Dialog.show("Push Error", "" + error, "OK", null);
    }
}
1 A client must implement the PushCallback interface in the main class of the application (the one with the callback methods)!
2 This sample requires a server that will accept the device id. Push is challenging without some central repository that will collect device ID’s from the clients
3 You get the GCM_SENDER_ID value from Google as discussed above
4 We register push every time we start the application, this is expected behavior since push details might change.
Notice that we wrap the call in a callSerially, this provides the first Form with time to appear. This is important as the user can be prompted for permissions at which point you wouldn’t want that prompt to show on top of a blank screen.
5 This method is invoked when a push message is received, it can be invoked multiple times for some cases
6 After registration push might still not be valid, it is only valid once this method is invoked. While it’s not essential to register in the server at this point, it’s probably what you should do.

Sending Push Messages

You can send a push message in many ways e.g. from another device or any type of server but there are some values that you will need regardless of the way in which you send the push message.

private static final String PUSH_TOKEN = "********-****-****-****-*************";

The push token is a unique "key" that you can use to send push thru your Codename One account. It allows you to send push messages without placing your Codename One email or password into your source files.

You can get it by going to the Codename One build server dashboard at https://www.codenameone.com/build-server.html and selecting the Account tab.

The token should appear at the bottom as such:

Push Token from the build server
Figure 8. Push Token from the build server

The instructions for extracting the API key for Google are listed above.

private static final String GCM_SERVER_API_KEY = "******************-********************";

When sending push to iOS devices we have two modes: - Production - Distribution

This allows you to debug the push related functionality without risking the possibility of sending a push into a production app. Its important to send the values to the right server during development/production.

private static final boolean ITUNES_PRODUCTION_PUSH = false;

iOS needs a certificate in order to send a push, this allows you to prove to Apples push servers that you are who you claim to be (the author of the app).

These are not the signing certificates and are completely separate from them!

You can obtain these two certificates (for development/appstore) via the certificate wizard as explained above.

private static final String ITUNES_PRODUCTION_PUSH_CERT = "https://domain.com/linkToP12Prod.p12";
private static final String ITUNES_PRODUCTION_PUSH_CERT_PASSWORD = "ProdPassword";
private static final String ITUNES_DEVELOPMENT_PUSH_CERT = "https://domain.com/linkToP12Dev.p12";
private static final String ITUNES_DEVELOPMENT_PUSH_CERT_PASSWORD = "DevPassword";
Sending a Push Message From Codename One

While normally sending a push message to a device should involve a server code there might be cases (e.g. instant messaging/social) where initiating a push from one client to another makes sense.

To simplify these use cases we added the Push API. To use the Push API you need the device key of the destination device to which you want to send the message. You can get that value from the Push.getPushKey() method. Notice that you need that value from the destination device and not the local device!

To send a message to another device just use:

String cert = ITUNES_DEVELOPMENT_PUSH_CERT;
String pass = ITUNES_DEVELOPMENT_PUSH_CERT_PASSWORD;
if(ITUNES_PRODUCTION_PUSH) {
    cert = ITUNES_PRODUCTION_PUSH_CERT;
    pass = ITUNES_PRODUCTION_PUSH_CERT_PASSWORD;
}
Push.sendPushMessage(PUSH_TOKEN, "Hello World",
         ITUNES_PRODUCTION_PUSH, GCM_SERVER_API_KEY, cert, pass, 1, deviceKey));

This will send the push message "Hello World" to the device with the key deviceKey. The 1 argument represents the standard push message type, we discuss push message types below.

Sending Push Message From A Java or Generic Server

Sending a push message from the server is a more elaborate affair and might require sending push messages to many devices in a single batch.

We can send a push message as an HTTP POST request to https://push.codenameone.com/push/push. That URL accepts the following arguments:

  • token - your developer token to identify the account sending the push - PUSH_TOKEN

  • device - one or more device keys to send the push to. You can send push to up to 500 devices with a single request -

  • type - the message type identical to the old set of supported types in the old push servers

  • body - the body of the message

  • auth - the Google push auth key - GCM_SERVER_API_KEY

  • production - true/false whether to push to production or sandbox environment in iOS - ITUNES_PRODUCTION_PUSH

  • certPassword - password for the push certificate in iOS push - ITUNES_DEVELOPMENT_PUSH_CERT_PASSWORD or ITUNES_PRODUCTION_PUSH_CERT_PASSWORD

  • cert - http or https URL containing the push certificate for an iOS push - ITUNES_DEVELOPMENT_PUSH_CERT or ITUNES_PRODUCTION_PUSH_CERT

We can thus send a push from Java EE using code like this:

URLConnection connection = new URL("https://push.codenameone.com/push/push").openConnection();
connection.setDoOutput(true);
connection.setRequestMethod("POST");
connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded;charset=UTF-8");
String cert = ITUNES_DEVELOPMENT_PUSH_CERT;
String pass = ITUNES_DEVELOPMENT_PUSH_CERT_PASSWORD;
if(ITUNES_PRODUCTION_PUSH) {
    cert = ITUNES_PRODUCTION_PUSH_CERT;
    pass = ITUNES_PRODUCTION_PUSH_CERT_PASSWORD;
}
String query = "token="  + PUSH_TOKEN +
    "&device=" + deviceId1 +
    "&device=" + deviceId2 +
    "&device=" + deviceId3 +
    "&type=1" +
    "&auth=" + GCM_SERVER_API_KEY +
    "&certPassword=" + URLEncoder.encode(pass, "UTF-8") +
    "&cert=" + cert +
    "&body=" + URLEncoder.encode(MESSAGE_BODY, "UTF-8") +
    "&production=" + ITUNES_PRODUCTION_PUSH;
try (OutputStream output = connection.getOutputStream()) {
    output.write(query.getBytes("UTF-8"));
}
int c = connection.getResponseCode();
// read response JSON

Notice that you can send a push to 500 devices. To send in larger batches you need to split the push requests into 500 device batches.

Server JSON Responses

The push servers send responses in JSON form. It’s crucial to parse and manage those as they might contain important information.

If there is an error that isn’t fatal such as quota exceeded etc. you will get an error message like this:

{"error":"Error message"}

A normal response, will be an array with results:

[
   {"id"="deviceId","status"="error","message"="Invalid Device ID"},
   {"id"="cn1-gcm-nativegcmkey","status"="updateId", "newId"="cn1-gcm-newgcmkey"},
   {"id"="cn1-gcm-okgcmkey","status"="OK"},
   {"id"="cn1-gcm-errorkey","status"="error","message"="Server error message"},
   {"id"="cn1-ios-iphonekey","status"="inactive"},
]

There are several things to notice in the responses above:

  • If the response contains status=updateId it means that the GCM server wants you to update the device id to a new device id. You should do that in the database and avoid sending pushes to the old key

  • iOS doesn’t acknowledge device receipt but it does send a status=inactive result which you should use to remove the device from the list of devices

APNS (Apple’s push service) returns uppercase key results. This means that code for managing the keys in your database must be case insensitive
Apple doesn’t always send back a result for a device being inactive and might fail silently
Various Types of Push Messages

The type argument when sending a push exposes many OS specific capabilities.

Notice that on iOS push messages will only trigger the push method if the app is in the foreground or if the user explicitly clicked the message!
  • 0, 1 - The default push types, they work everywhere and present the string as the push alert to the user

  • 2 - hidden, none visual push. This won’t show any visual indicator on any OS!
    In Android this will trigger the push(String) call with the message body. In iOS this will only happen if the application is in the foreground otherwise the push will be lost

  • 3 - 1 + 2 = 3 allows combining a visual push with a non-visual portion. Expects a message in the form: This is what the user will see;This is something he won’t see. E.g. you can bundle a special ID or even a JSON string in the hidden part while including a friendly message in the visual part.
    When active this will trigger the push(String) method twice, once with the visual and once with the hidden data.

  • 4 - Allows splitting a visual push request based on the format title;body to provide better visual representation in some OS’s.

  • 5 - Sends a regular push message but doesn’t play a sound when the push arrives

  • 100 - Applicable only to iOS. Allows setting the numeric badge on the icon to the given number. The body of the message must be a number e.g. unread count.

  • 101 - identical to 100 with an added message payload separated with a space. E.g. 30 You have 30 unread messages will set the badge to "30" and present the push notification text of "You have 30 unread messages".

Badging on iOS

The badge number can be set thru code as well, this is useful if you want the badge to represent the unread count within your application.

To do this we have two methods in the Display class: isBadgingSupported() & setBadgeNumber(int). Notice that even if isBadgingSupported will return true, it will not work unless you activate push support!

To truly utilize this you might need to disable the clearing of the badges on startup which you can do with the build hint ios.enableBadgeClear=false.

iOS Beta Testing (Testflight)

Apple provides the ability to distribute beta versions of your application to beta testers using testflight. This allows you to recruit up to 1000 beta testers without the typical UDID limits a typical Apple account has.

This is supported for pro users as part of the crash protection feature.

To take advantage of that capability use the build hint ios.testFlight=true and then submit the app to the store for beta testing. Make sure to use a release build target.

Accessing Insecure URL’s

Due to security exploits Apple blocked some access to insecure URL’s which means that http code that worked before could stop working for you on iOS 9+. This is generally a good move, you should use https and avoid http as much as possible but that’s sometimes impractical especially when working with an internal or debug environment.

You can disable the strict URL checks from Apple by using the venerable ios.plistInject build hint and setting it to:

<key>NSAppTransportSecurity</key><dict><key>NSAllowsArbitraryLoads</key><true/></dict>

However, it seems that Apple will reject your app if you just include that and don’t have a good reason.

Using Cocoapods

CocoaPods is a dependency manager for Swift and Objective-C Cocoa projects. It has over eighteen thousand libraries and can help you scale your projects elegantly. Cocoapods can be used in your Codename One project to include native iOS libraries without having to go through the hassle of bundling the actual library into your project. Rather than bundling .h and .a files in your ios/native directory, you can specify which "pods" your app uses via the ios.pods build hint. (There are other build hints also if you need more advanced features).

Examples

Include the AFNetworking library in your app:

ios.pods=AFNetworking

Include the AFNetworking version 3.0.x library in your app:

ios.pods=AFNetworking ~> 3.0

For full versioning syntax specifying pods see the Podfile spec for the "pod" directive.

Including Multiple Pods

Multiple pods can be separated by either commas or semi-colons in the value of the ios.pods build hint. E.g. To include GoogleMaps and AFNetworking, you could:

ios.pods=GoogleMaps,AFNetworking

Or specifying versions:

ios.pods=AFNetworking ~> 3.0,GoogleMaps

ios.pods.platform : The minimum platform to target. In some cases, Cocoapods require functionality that is not in older version of iOS. For example, the GoogleMaps pod requires iOS 7.0 or higher, so you would need to add the ios.pods.platform=7.0 build hint.

ios.pods.sources : Some pods require that you specify a URL for the source of the pod spec. This may be optional if the spec is hosted in the central CocoaPods source (https://github.com/CocoaPods/Specs.git).

Converting PodFile To Build Hints

Most documentation for Cocoapods "pods" provide instructions on what you need to add to your Xcode project’s PodFile. Here is an example from the GoogleMaps cocoapod to show you how a PodFile can be converted into equivalent build hints in a Codename One project.

The GoogleMaps cocoapod directs you to add the following to your PodFile:

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '7.0'
pod 'GoogleMaps'

This would translate to the following build hints in your Codename One project:

ios.pods.sources=https://github.com/CocoaPods/Specs.git
ios.pods.platform=7.0
ios.pods=GoogleMaps

(Note that the ios.pods.sources directive is optional).


1. Apple provided another trick with XIB files starting with iOS 8 but that doesn’t apply to games or Codename One. It has its own set of problems
2. slightly larger screen and different aspect ratio