DEVELOPERS BLOG

Good Dynamics SDK Part 6: What are GD Entitlement ID and Version?

byod_smartphone

In the Good Dynamics (GD) platform, every GD application has a unique identifier, the GD Entitlement ID, also referred to as the GD Application ID and Entitlement Version. These IDs and Versions are used in the Good Control (GC), the Good Developer Network (GDN), and anywhere else that GD applications must be identified. Understanding the concept as well as the usage of the GD Entitlement ID and Versions will help you to manage the life cycle of your GD applications.

This article is focused toward ISV partners who are integrating with the GD SDK for their apps but the information is relevant to other developers as well.

GD Entitlement ID and Entitlement Version: Both Required for All GD Apps

A primary purpose of the GD Entitlement ID and Version is to manage end-user entitlement for your GD application. You need to define both the GD Entitlement ID and the Entitlement Version for all your GD-based applications. These identifiers are also used in support of Inter Container Communication (ICC).

Format of GD Entitlement ID and Version Values

The general form of a GD Entitlement ID is: com.your_company_name.your_application

And the value of your GD Entitlement IDs must follow these rules:

  • Must be in reverse domain name form, like yourcompany.something.
  • Must not begin with any of the following: “good
  • No uppercase letters.

By convention, the Entitlement Version numbers are four integers separated by full stops; e.g., “1.0.0.0,” which is commonly the version number for the first release of a GD application.

Difference from Native Identifiers and Versions

The GD Entitlement ID and Entitlement Version are Good-specific metadata and are independent of the native platform’s package names (Android) or bundle identifiers (iOS). Therefore, you don’t have to keep the GD Entitlement ID and Versions the same as those native package identifiers and versions.

It is also recommended that you do not associate your GD Entitlement ID with any platform specific information, like com.yourcompany.your_gd_app_ios. Instead, a single GD Entitlement ID should be used for all versions of an application on all platforms.

Also, the version number associated with GD Entitlement IDs should be kept independent of your application’s versioning scheme on different platforms. For example, your GD Entitlement Version might be “1.0.0.0” while you publicly show the application’s version number as “2.1”.

GD Application Entitlement

The entitlement of ISV apps can be managed via GDN by publishing the GD app to customers. Once the app is published to customers, the entitlement of end users to applications is managed in the GC console. GC administrators can entitle users to specific GD apps based on the application’s GD entitlement ID and entitlement version. Therefore, developers and GC administrators should ensure that the values specified for the GD entitlement ID and version in a GD app’s application configuration file(s) are the same as the values that the administrator specifies in Good Control.

When an end user’s GD application entitlement is changed, GC immediately notifies the NOC, which stores the new entitlement. If an end user’s device is running a GD app to which they are not entitled, and the application is online, the change is enforced immediately. Otherwise, the change is enforced when the application next connects to the NOC.

Enforcement of removed entitlement includes deleting the enterprise data from the device.

When to Change the GD Entitlement Version?

Because each new GD Entitlement Version of your GD application requires publishing it to your existing customers, it is not recommended to change the GD Entitlement Version number frequently. There are three primary reasons to change the GD Entitlement Version number:

  1. To provide early access, beta, or limited access to a new version for specific customers: For ISVs, after the new version has been published to all customers, revert back to the original version number.
  2. To monetize new functionality differently from your existing version.
  3. To represent large level differences in GD functionality (not your own app’s functionality): For example, you might update a service definition, that is, publish a service update that is not supported on an older GD Entitlement Version.

When a new version is to be made available,

  1. Ensure that the new version is published to the Marketplace, if you are an ISV partner, or on the GC console for custom applications, before the GD application is available in the App Store, Play Store or elsewhere.
  2. Ensure the services that are associated with the GD application are also published for the same entitlement version.

If the new version of the application is downloaded to a device before the version is published on GDN or in GC, the application is blocked. You should avoid delisting a version unless it is to enforce payment, force end-of-life, or remove a version with a fatal security issue. If a GD Entitlement ID or Entitlement Version is ever unpublished or an end-user unentitled from a previously entitled application, the container is wiped from end-user devices for all end-users who installed the application.

For more information, check out the documents, GD SDK Getting Started on iOS and GD SDK Getting Started on Android via GDN.

That’s it for now.

@echotown

EK Choi

About EK Choi

EK is a member of the Enterprise Solutions Team, helping developers to create secure applications using BlackBerry solutions and services.