Documentation

Let's get familiar with Pushlink features

Download

JAR File

pushlink-android-5.5.2.jar

Maven

Gradle


How to use Pushlink?

  1. Sign up to receive an API key
    After login, you are going to see this in the menu bar. Click to copy to the clipboard.
  2. Add Pushlink JAR to the classpath
    You can choose between gradle, maven or raw jar file.
  3. Add in AndroidManifest.xml
    <uses-permission android:name="android.permission.INTERNET" />
    <provider android:name="com.pushlink.android.FileProvider" android:authorities="your.package.name" android:exported="true" />
    Don't forget to replace "your.package.name" with your current application package name.
  4. Make sure you've read the Android Device ID Guide
  5. Call PushLink.start() inside android.app.Application.onCreate()
    Because it certainly will be called when your process start/restart. Also, it must be called in the UI Thread.
    Don't call the start method inside onCreate of an Activity.
  6. Build the APK and upload it to Pushlink.
    If you are using Android Studio 3 you need to build the APK, not just run. Take a look at Android Studio 3 and FLAG_TEST_ONLY
Why am I getting 'There was a problem parsing the package' after initiating the installation process?
List of possibilities:
  • You are using old pushlink version with Android 7 that requires >= 5.5.2 + FileProvider . In this case you are going to see the error 'java.lang.SecurityException: MODE_WORLD_READABLE no longer supported' in logcat.
  • You are generating testOnly APK's. Take a look at Android Studio 3 and FLAG_TEST_ONLY.
  • You forgot to bump the version code.

Concerned about security?


Network

It's very common to run Pushlink behind a firewall in a LAN environment. See the names we use:


Android & Downgrade

Android has changed its behaviour when installing a new apk file. Until ICS (ice cream sandwich), it didn't mater if the new apk had a lower or higher android:versionCode in AndroidManifest.xml. After that, it's mandatory a higher versionCode. In fact, we can't guarantee "when" the new behavior was introduced, but we noticed it was sometime around Jelly Bean.

When trying to install a lower version code through adb, you will get the message: INSTALL_FAILED_VERSION_DOWNGRADE. In this case you can force with the undocumented -d flag: adb install -r -d my.apk. Pushlink can't force it because it just launches the apk and the control is passed to the OS. So, the installation process will fail with no specific error message.

Keep in mind that Pushlink can't perform downgrades when the OS does not allow.

Android 7

Android 7 (Nougat) Build.VERSION.SDK_INT >= 24 requires a FileProvider in the AndroidManifest.xml, otherwise Pushlink will not work.

Don't forget to replace your.package.name with your current application package name.

Pushlink supports Android N since version 5.5.2 released in 2016.11.11.

Status Bar

Default Pushlink Strategy
  • PushLink.setCurrentStrategy(StrategyEnum.STATUS_BAR);
  • Title message: "New version of [App Name]".
  • Description message: "Click to Update".
  • Remains on status bar until the installation happens.
  • Clear the message if the admin changes back to an earlier version before the installation.
Pushlink status bar strategy

Friendly Popup

Useful for fullscreen apps
  • PushLink.setCurrentStrategy(StrategyEnum.FRIENDLY_POPUP);
  • Default message: "New version of [App Name]. Do you want to update it?".
  • Default buttons: [Not Now][Update].
  • Remains until the user press [Not Now] or [Update] (Back button is blocked).
  • Default reminder: 3 hours
  • Hide the popup if the admin changes back to an earlier version before the installation.
Pushlink friendly popup strategy
Important

Don't forget to call PushLink.setCurrentActivity(this); inside onResume


Annoying Popup

Useful for fullscreen apps when updates can't wait
  • PushLink.setCurrentStrategy(StrategyEnum.ANNOYING_POPUP);
  • Default message: "For security reasons [App Name] needs to be updated!"
  • Default button: [Update].
  • Very insistent. Remains until the user press [Update] (Dismiss button is blocked).
  • Hide the popup if admin changes back to an earlier version before the installation.
Pushlink annoying popup strategy
Important

Don't forget to call PushLink.setCurrentActivity(this); inside onResume


Background

Useful for Kiosk / Point of Sale (POS) applications. There isn't notification. Silent update with no user interaction.
Pushlink covers 100% of this need with two strategies:
  • For Android <= 4 just use NINJA. (it requires a ROOTED device)
  • For Android >= 5 just use CUSTOM. (it requires ADMIN PRIVILEGES on device)
Do you want to perform background updates only when your app is idle?
Check the PushLink.idle(boolean) in the Javadoc.
Pushlink ninja strategy
NINJA (Only for rooted devices)
NINJA Disclaimer

NINJA worked flawlessly until android 4. 🤘

When android 5 was released NINJA began to have issues and we was forced to implement a <receiver android:name="com.pushlink.android.NinjaReceiver" /> to make it work. Unfortunately it was not fixed completely and it still can fails sometimes, depending the combination of OS version x Vendor. 😕

So if you have Android >= 5, the better choice is CUSTOM with admin privileges on device.

CUSTOM (Take full control of your installation)
Sample:

Customization

You can customize the built in strategies like this:


Monodroid


Phonegap/Cordova


Metadata

Add some metadata to identify the device/user:


Manual Checking

PushLink.hasPendingUpdate() is designed to notify again a skipped update using friendlypopup before the reminder tick. If there is a new version but it wasn't downloaded yet, this method returns FALSE.


Exception Notification

  1. Pushlink catches all unhandled exceptions in your app by default. It doesn't block the natural exceptions life cycle.
  2. You can also send handled exceptions calling PushLink.sendAsyncException().
  3. Pushlink always sends the exceptions asynchronously and garantees its delivery.
  4. If you also want to get the last 100 LogCat's lines, just add android.permission.READ_LOGS in AndroidManifest.xml
Sending limit
Logcat messages

API Docs


Metadata API

To get XML output:

https://www.pushlink.com/apps/api_list_xml?packageName=some.package.name&apiKey=yourApiKey

To get JSON output:

https://www.pushlink.com/apps/api_list_json?packageName=some.package.name&apiKey=yourApiKey

Upload API

After uploading you might set the apk as current manually in the web administration

curl -F "apiKey=yourApiKey" -F "apk=@yourApp.apk" https://www.pushlink.com/apps/api_upload

or, set the current apk in upload time

curl -F "apiKey=yourApiKey" -F "apk=@yourApp.apk" -F "current=true" https://www.pushlink.com/apps/api_upload

Raw text responses:

Download API

Download the current APK
curl -o yourApp.apk 'https://www.pushlink.com/download?package=some.package.name&api_key=yourApiKey'

Changelog

PushLinkAndroid-5.5.2.jar 2016.11.11
  • Now it works on android 7 (Nougat) [Build.VERSION.SDK_INT >= 24]. It requires a <provider android:name="com.pushlink.android.FileProvider" android:authorities="your.package.name" android:exported="true" /> in AndroidManifest.xml
  • Now pushlink cleanup old downloaded apks.
  • New custom strategy is available.
PushLinkAndroid-5.5.0.jar 2016.04.18
  • Fixed ninja NPE when using broadcast receiver
PushLinkAndroid-5.4.5.jar 2016.03.13
  • Ninja fallback. (If broadcast receiver is not present, it uses the classic ninja.)
  • Commons network exceptions now are debug level in logcat
PushLinkAndroid-5.4.4.jar 2016.03.01
  • Ninja now works in android 5 or higher. Its requires the <receiver android:name="com.pushlink.android.NinjaReceiver" /> in AndroidManifest.xml
  • Ninja.setExtraShellCommand() deprecated in favor to Pushlink.setBeforeNinjaTaskShellCommand()
  • Available from Maven and Gradle by jitack
PushLinkAndroid-5.4.2.jar 2015.12.03
  • Bug fix: Pushlink.hasPendingUpdate() does not ignore the idle status anymore (Pushlink.idle method)
PushLinkAndroid-5.4.1.jar 2015.11.25
  • Now Ninja is working in Android 64 bits
  • Ninja does not execute the export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/system/lib command anymore
  • New method Ninja.setExtraShellCommand() for custom workarounds
  • Now Pushlink logs the entire stack trace. (No more clipping)
PushLinkAndroid-5.4.0.jar 2015.09.30
  • Fixed critical bug when using android:process
  • New api method Pushlink.setMaxExceptionQueueSize() (to avoid huge cache)
PushLinkAndroid-5.3.0.jar 2015.04.02
  • Download resume. (Very welcome!)
  • Bug fix that would send old exception assigned with wrong version label.
  • Bug fix that in Pushlink.addMetadata() and Pushlink.addExceptionMetadata() when key == null. Not allowed anymore.
  • Now it prevents to send the very same exception twice or more.
  • Less data transfer when using the metadata api.
  • Now Pushlink.setCurrentActivity() and Pushlink.setCurrentStrategy() are independent of start method.
  • Some timeout adjustments
PushLinkAndroid-5.1.0.jar 2013.12.14
  • NINJA strategy improved. Now working in a large variety of devices.
  • Now PushLink uses only the 443 port. Goodbye 6670 port.
PushLinkAndroid-5.0.4.jar 2013.11.12
  • Download method improved to avoid memory overflow.
  • Popup strategies no more play notification sound.
  • Now popup strategies ask for launching the app even in ICS or later.
PushLinkAndroid-5.0.3.jar 2013.07.31
  • Now it sends the last 200 lines of logcat. (no more 100)
  • Now exceptions has a handled/unhandled label
  • New method PushLink.addExceptionMetadata(). This metadata is going to appear ONLY in the "Exceptions" tab of the web administration
PushLinkAndroid-5.0.2.jar 2013.06.17
  • Important bug fix. PushLink.addMetadata wasn't working fine.
  • TCP client improvement. It was aborting connections sometimes.
  • Installation checking for duplicated ID's improved.
  • Method name changed! PushLink.setCurrentPopUpTarget() is now PushLink.setCurrentActivity().
  • Now PushLink grabs screenshots for unhandled exceptions.
PushLinkAndroid-5.0.1.jar 2013.02.21
  • Logging improvements
  • Bug fix. Calling PushLink.setCurrentStrategy() before PushLink.start() had no effect.
PushLinkAndroid-5.0.0.jar 2013.02.06
  • Package change. Now all classes are under "com.pushlink.android"
  • Critical bug fix. Heartbeat was not working when devices were sleeping.
  • Device ID is back. Now the user MUST set the device id. Now the web administration show off-line installations again.
  • Api change to support device ID: Now PushLink.start() has a brand new fourth parameter. The device ID.
  • Method name changed from PushLink.sendAsyncNotification() to PushLink.sendAsyncException().
  • Pushink now has two lightweight threads. They were named as "PushLink-PushListener" and "PushLink-Heartbeat".
PushLinkAndroid-4.2.1.jar 2012.12.25
  • Huge logging improvements
PushLinkAndroid-4.2.0.jar 2012.12.17
  • Critical bug fix. Low socket/connection timeout was killing some APK downloads.
  • Now exceptions are always send lazily with delivery guarantee. PushLink holds the exception (sqlite persistence) until it can be sent to the server. PushLink.sendSyncException() was removed.
  • New method PushLink.hasPengingUpdate(). This method checks if there is a downloaded but not applied update. It also notify the user again.
  • Log messages improved
PushLinkAndroid-4.1.1.jar 2012.11.12
  • PushLink.sendExceptionNotification() has changed to PushLink.sendAsyncException() and PushLink.sendSyncException()
  • Fixed NPE when Pushlink.setCurrentPopUpTarget() called before PushLink.start()
  • When popup strategies were configured before PushLink.start, the popup title would appear "Application" instead the real application name. Fixed!
  • Log messages improved
PushLinkAndroid-4.1.0.jar 2012.09.26
  • Lighter. HttpClient code improvement. Less data transfered between server and client.
PushLinkAndroid-4.0.0.jar 2012.09.14
  • Popups strategies now supports screen rotation
  • It is ready to show online installations in the web administration
  • Fixed some minor bugs that could happen in push notification
  • PushLink.addGlobalInfo() has changed to PushLink.addMetadata()
PushLinkAndroid-3.1.3.jar 2012.07.27
  • Fixed a NPE that would appear in some cases
  • Fixed some confusing log informations
PushLinkAndroid-3.1.2.jar 2012.06.06
  • API method PushLink.idle(boolean) added. Especially useful for NINJA strategy to update your app only when it is idle. See the usage in JAVADOC.
  • Now it sends device coordinates if the GPS is enabled. This is sent only once when the app is started.
PushLinkAndroid-3.1.1.jar 2012.05.04
  • Bug fixed. It could happen to receive several notifications to the same version in some specific situations.
PushLinkAndroid-3.1.0.jar 2012.04.23
  • NINJA strategy has been created. Only for rooted devices. BETA!
  • Logging improvements.
PushLinkAndroid-3.0.0.jar 2012.04.20
  • Full redesing to support premium features.
  • PushLink.checkForUpdates() in no longer available. There is no sense using it the new push architecture.
  • PushLink.start() method has changed. Now it has only three parameters
  • Notification now play standrd device sound
  • Automatic exception catch/send notification is the default.
  • Added two method. PushLink.disableExceptionNotification() and PushLink.enableExceptionNotification
PushLinkAndroid-2.0.4.jar 2012.03.07
  • Push.addUserInfoForExceptionNotification() is now Push.addGlobalInfo. This information is going to appear in all exceptions notifications sent.
  • Push.sendExceptionNotification(Throable) was overloaded with Push.sendExceptionNotification(Throwable, Map). Now it's possible to send more information about the exception context in Map.
  • Professional JAVADOC added
PushLinkAndroid-2.0.3.jar 2012.03.04
  • Push.requestUpdateRightNow is now Push.checkForUpdates
  • Now Push.checkForUpdates() does not block the thread anymore.
  • Push.checkForUpdates bug fix. It was rushing the download but not the notification.
PushLinkAndroid-2.0.2.jar 2012.02.20
  • Now if exceptionNotification is set to false and you call PushLink.sendExceptionNotification() it will not throw an exception anymore. It only will log: "You must start pushlink enabling exception notification before using PushLink.sendExceptionNotification or PushLink.addUserInfoForExceptionNotification. Check PushLink.start method exceptionNotification parameter."
PushLinkAndroid-2.0.1.jar 2012.02.01
  • Exception notification now sends LogCat (Need READ_LOGS permission)
  • Exception notification now sends the whole stack trace
  • Fixed some exception notification bugs
PushLinkAndroid-2.0.0.jar 2012.01.20
  • API Redesigned. All PushLink's method are static.
  • There is no method Pushlink.stop() anymore.
  • Now we have exception notification! Recieve emails when your app crashes.
  • New API method Pushlink.requestUpdateRightNow() to rush version check.
PushLinkAndroid-1.1.3.jar 2011.12.01
  • Now popups strategies work nice with PushLink.setCurrentPopUpTarget()
PushLinkAndroid-1.1.2.jar 2011.11.22
  • Fixed java.lang.NoClassDefFoundError: com.pushlink.android.SSLHandler when runnig on ADT emulator
PushLinkAndroid-1.1.1.jar 2011.11.17
  • Pop Up strategy support
  • i18n support
PushLinkAndroid-1.1.0.jar 2011.11.03
  • SSL Support
  • Internal storage bug fix
PushLinkAndroid-1.0.0.jar 2011.10.28
  • Beta test