TurkcellUpdater Android SDK
This library provides mechanism for updating Android applications and displaying messages configured at a configuration file.
Gradle
Add it in your root build.gradle at the end of repositories:
allprojects {
repositories {
...
maven { url 'https://jitpack.io' }
}
}
Add below dependency to your app's build.gradle file.
dependencies {
compile 'com.github.Turkcell:TurkcellUpdater_android_sdk:1.2.4'
}
Configuration Guide
This documents describes usage and structure configuration files used by Turkcell Updater library.
Usage
Updating an Android application to a new version served on Google Play
{
"packageName": "com.example.app1",
"updates": [
{
"descriptions": {
"tr": {
"message": "Yeni versiyon yayınlanmıştır",
"positive_button": "Güncelle",
"negative_button": "İptal"
},
"*": {
"message": "New version available",
"positive_button": "Update",
"negative_button": "Cancel"
}
},
"targetVersionCode": 1,
"targetGooglePlay": true
}
]
}
Updating an Android application to a new version served as APK file
{
"packageName": "com.example.app1",
"updates": [
{
"descriptions": {
"tr": {
"message": "Yeni versiyon yayınlanmıştır",
"positive_button": "Güncelle",
"negative_button": "İptal"
},
"*": {
"message": "New version available",
"positive_button": "Update",
"negative_button": "Cancel"
}
},
"targetVersionCode": 1,
"targetPackageUrl": "http://example.com/app1-v10.apk"
}
]
}
Updating an Android application depending on where current application is installed from
{
"packageName": "com.example.app1",
"updates": [
{
"filters": {
"appInstallerPackageName": "com.android.vending"
},
"descriptions": {
"tr": {
"message": "Yeni versiyon yayınlanmıştır",
"positive_button": "Güncelle",
"negative_button": "İptal"
},
"*": {
"message": "New version available",
"positive_button": "Update",
"negative_button": "Cancel"
}
},
"targetVersionCode": 1,
"targetGooglePlay": true
},
{
"filters": {
"appInstallerPackageName": "!com.android.vending"
},
"descriptions": {
"tr": {
"message": "Yeni versiyon yayınlanmıştır",
"positive_button": "Güncelle",
"negative_button": "İptal"
},
"*": {
"message": "New version available",
"positive_button": "Update",
"negative_button": "Cancel"
}
},
"targetVersionCode": 1,
"targetPackageUrl": "http://example.com/app1-v10.apk"
}
]
}
Forcing an Android application to update
{
"packageName": "com.example.app1",
"updates": [
{
"descriptions": {
"tr": {
"message": "Yeni versiyon yayınlanmıştır",
"positive_button": "Güncelle",
"negative_button": "Çıkış"
},
"*": {
"message": "New version available",
"positive_button": "Update",
"negative_button": "Exit"
}
},
"targetVersionCode": "1",
"targetGooglePlay": true,
"forceUpdate": true
}
]
}
Forcing an Android application to quit
{
"packageName": "com.example.app1",
"updates": [
{
"descriptions": {
"tr": {
"message": "Hizmet kullanılamıyor",
"positive_button": "Çıkış"
},
"*": {
"message": "Service is unavailable",
"positive_button": "Exit"
}
},
"forceExit": true
}
]
}
End of support for older Android OS versions
{
"packageName": "com.example.app1",
"updates": [
{
"filters": {
"deviceApiLevel": ">=8"
},
"descriptions": {
"tr": {
"message": "Yeni versiyon yayınlanmıştır",
"positive_button": "Güncelle",
"negative_button": "Çıkış"
},
"*": {
"message": "New version available",
"positive_button": "Update",
"negative_button": "Exit"
}
},
"targetVersionCode": "5",
"targetGooglePlay": true,
"forceUpdate": true
},
{
"filters": {
"deviceApiLevel": "<8"
},
"descriptions": {
"tr": {
"message": "Android 2.2 ve üzeri versiyonlar desteklenmektedir.",
"positive_button": "Çıkış"
},
"*": {
"message": "Android version earlier than Android 2.2 are not supported.",
"positive_button": "Exit"
}
},
"forceExit": true
}
]
}
Transferring users to another Android application replacing old one
{
"packageName": "com.example.app1",
"updates": [
{
"descriptions": {
"*": {
"message": "New version available",
"positive_button": "Update"
}
},
"targetPackageName": "com.example.newapp",
"targetVersionCode": "5",
"targetGooglePlay": true,
"forceUpdate": true
}
]
}
Adding "What is new in this version" message
{
"packageName":"com.example.app1",
"messages":[
{
"filters":{
"appVersionCode":"1.1.0.0",
"deviceOsName":"Android"
},
"descriptions":{
"tr":{
"title":"Bu Versiyonda Neler Yeni",
"message":"Bazi hatalar duzeltildi ve iyilestirmeler yapildi.",
"positive_button": "Tamam"
},
"*":{
"title":"What's New in this Version",
"message":"We made our app even cooler with some incredible bugfixes.",
"positive_button": "Ok"
}
},
"maxDisplayCount":1,
"targetWebsiteUrl":"http://mysite.com?q=learn+more"
}
]
}
Reference
Different configuration files are stored per application using Turkcell Updater Library.
Configuration files are UTF-8 encoded JSON documents and should be served with
"application/json"
content type.
Since configurations may contain vulnerable information like URL of update package they should be only accessible via HTTPS.
Root element of files should conform to
Configuration Root specifications below.
Documents may contain additional keys but Updater library ignores any other key that is not referred in this document.
Configuration Root
Root object that contains all data needed by Updater Library to show update messages and other notifications to user.
Structure:
Type: Object
Property name |
Type |
Default value |
Platforms |
Description |
Required |
Since |
packageName |
String |
null |
All |
Platform specific unique identifier of application which configuration is created for. Package name for Android applications or Bundle id for iOS applications. |
Yes |
1 |
updates |
Array |
null |
All |
List of update entries with 0 or more elements. See Update Entry |
No |
1 |
messages |
Array |
null |
All |
List of messages with 0 or more elements. See Message Entry |
No |
2 |
Example:
Android
{
"packageName": "com.example.app1",
"updates": [
{
"descriptions": {
"tr": {
"message": "Yeni versiyon yayinlandi",
"whatIsNew": "Bazi hatalar duzeltildi",
"warnings": "Yeni versiyon ek izinler gerektiriyor",
"positive_button": "Tamam"
},
"*": {
"message": "New version available",
"whatIsNew": "Minor bug fixes",
"warnings": "New version requires additional privileges",
"positive_button": "Ok"
}
},
"targetVersionCode": 10,
"targetPackageUrl": "http://example.com/app1-v10.apk",
"forceUpdate": false
}
],
"messages": [
{
"descriptions": {
"tr": {
"title": "Teklif",
"message": "Yeni uygulama mevcut!",
"imageUrl": "http://example.com/app2-icon.png",
"positive_button": "Yukle",
"negative_button": "Daha Spnra"
},
"*": {
"title": "Offer",
"message": "New application is available!",
"imageUrl": "http://example.com/app2-icon.png",
"positive_button": "Install",
"negative_button": "Later"
}
},
"targetPackageName": "com.example.app2",
"targetGooglePlay": true,
"maxDisplayCount": 3
}
]
}
Update Entry
Provides information about how update should be installed and when update should be applied.
Structure:
Type: Object
Property name |
Type |
Default value |
Platforms |
Description |
Required |
Since |
filters |
Array |
null |
All |
See Filter Entry |
No |
1 |
descriptions |
Object |
null |
All |
Map of update description entries. Keys (property names) are two letter language codes (see: ISO 639-1) and values are Update Description Entries.
If empty strings ("") or asterisk("*") is used as key, it matches with any language.
For iOS : If device language is English but the application language is Turkish asterisk("*")language code is suggested for displaying Turkish descriptions. |
Yes |
1 |
targetVersionCode |
Number |
-1 |
Android |
Version code of new version. See Note #1 |
Yes for Android application, unless forceExit is true |
1 |
targetGooglePlay |
Boolean |
false |
Android |
true New version should be installed from Google Play. |
See Note #2 |
1 |
targetPackageName |
String |
Current application's packageName |
Android |
Package name of new version. |
No |
1 |
targetPackageUrl |
String |
null |
Android |
URL of APK package of new version. |
See Note #2 |
1 |
forceUpdate |
Boolean |
false |
All |
true if user should not skip this update and continue to use application. When true "Exit application" option will be displayed to user instead of "Remind me later" option. |
No |
1 |
forceExit |
Boolean |
false |
All |
true if user should not have any option other than exiting application. When true only "Exit application" option will be displayed to user. |
No |
2 |
targetWebsiteUrl |
String |
null |
All |
For Android : URL of web page that contains new version.
For iOS : iTunes or Corporate Repository URL of the application. |
See Note #2 |
1 |
Notes:
- Version entries will be omitted if
targetPackageName
is same with current applications package name and targetVersionCode
is same with current applications version code. This check is performed in order avoid updates to existing version.
- On Android, any update entry should meet at least one of following conditions. Otherwise it will be omitted.
forceExit
is true
targetGooglePlay
is true
targetWebsiteUrl
is not null
or empty
targetPackageUrl
is not null
or empty
Example:
{
"filters": {
"appVersionCode": "<10",
"deviceOsName": "Android"
},
"descriptions": {
"tr": {
"message": "Uygulamanın yeni sürümü yayınlandı.",
"whatIsNew": "Hata düzeltildi",
"warnings": "Yeni sürüm ek yetkiler gerektirir"
},
"*": {
"message": "New version available",
"whatIsNew": "Minor bug fixes",
"warnings": "New version requires additional privileges"
}
},
"targetVersionCode": 10,
"targetGooglePlay": true
}
Message Entry
Defines a message to display to user when message should be displayed.
Structure:
Type: Object
Property name |
Type |
Default value |
Platforms |
Description |
Required |
Since |
filters |
Array |
null |
All |
See Filter Entry |
No |
2 |
descriptions |
Object |
null |
All |
Map of message description entries. Keys (property names) are two letter language codes (see: ISO 639-1) and values are Message Description Entries.
If empty strings ("") or asterisk("*") is used as key, it matches with any language. |
Yes |
2 |
id |
Number |
For Android : Auto generated value using targetGooglePlay , targetPackageName , targetWebsiteUrl and descriptions properties.
For iOS : Auto generated value using targetWebsiteUrl and descriptions properties. |
All |
Unique ID of message. ID is used when determining last display date and total display count of message. |
No |
2 |
targetGooglePlay |
Boolean |
false |
Android |
true if message offers references to an application in Google Play. If it is true , targetPackageName should not be null or empty. |
No |
2 |
targetPackageName |
String |
null |
Android |
Package name of offered application. If specified one of targetGooglePlay or targetWebsiteUrl properties should be set. |
No |
2 |
targetWebsiteUrl |
String |
null |
All |
URL of web page that contains offered application. |
No |
2 |
maxDisplayCount |
Number |
2147483647 |
All |
Maximum display count of message |
No |
2 |
displayBeforeDate |
String |
null |
All |
If not null, message should not be displayed after this date. For date format details see Note #1 |
No |
2 |
displayAfterDate |
String |
null |
All |
If not null, message should not be displayed before this date. For date format details see Note #1 |
No |
2 |
displayPeriodInHours |
Number |
0 |
All |
Minimum duration in hours that should pass before displaying this message again |
No |
2 |
Notes:
- Following date formats from ISO 8601 are supported:
- "yyyy-MM-dd" example: "1969-12-31" "1970-01-01"
- "yyyy-MM-dd HH:mm" example: "1969-12-31 16:00", "1970-01-01 00:00"
Example:
Android
{
"filters": {
"deviceIsTablet": "true"
},
"descriptions": {
"*": {
"title": "Offer",
"message": "New application for your tablet is avaliable!",
"imageUrl": "http://example.com/app2-icon.png"
}
},
"displayAfterDate": "2013-01-01",
"displayBeforeDate": "2013-06-01",
"targetPackageName": "com.example.app2",
"targetGooglePlay": true,
"maxDisplayCount": 10,
"displayPeriodInHours": 240
}
Filter Entry
Message Entries and
Update Entries are applied only
if filter matches with device properties. If "filter" property of a
Message Entry and a
Update Entry
is omitted or defined as null no filtering will be applied.
Filter entries consist of key and value pairs.
Keys are property names and values are filtering rules.
Filtering rules format applies to all values of filter entry:
- Rules are sequences of rule parts joined with ","
- Both rule parts and values are converted to lower case and trimmed before
comparison
- Order of rule parts doesn't change the result, example: "!b,a" is same with "a,!b"
"*"
, null
or empty string matches with any value including
null
"''"
matches with null
or empty string
"!''"
matches with any value except null
or empty string
"![rule part]"
excludes any value matches with [rule]
"[value]"
matches with any value equals to [value]
"[prefix]*"
matches with any value starting with [prefix]
"*[suffix]"
matches with any value ending with [suffix]
"[prefix]*[suffix]"
matches with any value starting with [prefix] and
ending with [suffix]
">[integer]"
matches with any value greater than [integer]
">=[integer]"
matches with any value greater than or equals to [integer]
"<[integer]"
matches with any value lesser than [integer]
"<=[integer]"
matches with any value lesser than or equals to [integer]
"<>[integer]"
matches with any value not equals to [integer]
Structure:
Type: Object
Property name |
Type |
Default value |
Platforms |
Description |
Required |
Since |
appPackageName |
String |
null |
All |
Filter rule for package name of application.
Example value: "com.sample.app".
|
No |
1 |
appVersionName |
String |
null |
All |
Version name of application typically in Major.Minor.Revision or Major.Minor format.
Example value: "1.0.0"
|
No |
1 |
appVersionCode |
String |
null |
Android |
An integer version code of application which is defined in AndroidManifest.xml.
Example value: "10"
|
No |
1 |
appInstallerPackageName |
String |
null |
Android |
Package name of application installed current application. Maybe null if not specified.
Example value: "com.android.vending" of Google play.
|
No |
1 |
deviceApiLevel |
String |
null |
Android |
Version code of Android OS. See Android documentation.
Example value: "10" for Android 2.3.3.
|
No |
1 |
deviceOsName |
String |
null |
Android |
Name of operating system of device.
Values: "android", "ios", "windowsphone".
|
No |
1 |
deviceOsVersion |
String |
null |
All |
Version name of operating system of device.
Example value: "2.3.3".
|
No |
1 |
deviceBrand |
String |
null |
Android |
Brand name of device.
Example value: "htc_europe" for HTC Wildfire S.
|
No |
1 |
deviceModel |
String |
null |
All |
For Android : Model name of device.
Example value: "HTC Wildfire S A510e" for HTC Wildfire S.
For iOS :
- "iPod1,1" for iPod Touch
- "iPod2,1" for iPod Touch Second Generation
- "iPod3,1" for iPod Touch Third Generation
- "iPod4,1" for iPod Touch Fourth Generation
- "iPhone1,1" for iPhone
- "iPhone1,2" for iPhone 3G
- "iPhone2,1" for iPhone 3GS
- "iPad1,1" for iPad
- "iPad2,1" fpr iPad 2
- "iPad3,1" for iPad 3 (aka new iPad)
- "iPhone3,1" for iPhone 4
- "iPhone4,1" for iPhone 4S
- "iPhone5,1" for iPhone 5
If there is a need for giving multiple device models as a value asterik(*) must be used instead of comma(,) ,
because comma(,) is a reserved notation for joining rules.
Example value: "iPhone2*,iPad1*,iPhone5*"
|
No |
1 |
deviceProduct |
String |
null |
Android |
Product name of the device.
Example value: "htc_marvel" for HTC Wildfire S.
|
No |
1 |
deviceIsTablet |
String |
null |
All |
"true" if devices is a tablet, otherwise "false".
For Android : Since there is no clear evidence to determine if an Android device
is tablet or not, devices with minimum screen size wider than 600 dpi are considered as tablets.
Example values: "true", "false".
|
No |
1 |
deviceLanguage |
String |
null |
All |
Two letter language code of device
(see: ISO 639-1).
Example values: "en", "tr", "fr".
|
No |
1 |
x-<Application defined key> |
String |
null |
Android |
"x-" is prefix for application defined keys of arbitrary properties.
Applications may define and add own custom property key-value pairs for application specific filters.
Example values: "x-foo", "x-bar".
|
No |
1 |
deviceMcc |
String |
null |
Android |
Mobile country code of device. See Mobile country code
Example value: "286" for Turkey.
|
No |
1 |
deviceMnc |
String |
null |
Android |
Mobile network code of device. See Mobile country code
Example value: "1" for Turkcell.
|
No |
1 |
updaterLevel |
String |
null |
Android |
An integer number that is used to define updater version used by application.
Example value: "1" for initial version of updater sdk.
|
No |
1 |
Example:
{
"deviceOsName": "android",
"deviceOsVersion": "4.*",
"appVersionName": "2.4.3, 2.4.4, 2.5.*, 3.*, 4.*, 5.*",
"deviceIsTablet": "true"
}
Update Description Entry
Contains language specific texts that are displayed to user on updates found dialog.
See
Update Entry
Structure:
Type: Object
Property name |
Type |
Default value |
Platforms |
Description |
Required |
Since |
message |
String |
null |
All |
Summary information describing update contents.
|
Yes |
1 |
whatIsNew |
String |
null |
All |
Describes changes and new features of new version.
|
No |
1 |
warnings |
String |
null |
All |
Warning text about the update. Any important issues that user should know before updating should be described here.
|
No |
1 |
positive_button |
String |
null |
Android |
Text that will be displayed at positive button of message dialog.
|
Yes |
3 |
negative_button |
String |
null |
Android |
Text that will be displayed at negative button of message dialog.
|
No |
3 |
Example:
{
"message": "New version available",
"whatIsNew": "Minor bug fixes",
"warnings": "New version requires additional privileges",
"positive_button": "Install",
"negative_button": "Later"
}
Message Description Entry
Contains language specific texts that are displayed to user on message dialog.
See
Message Entry
Structure:
Type: Object
Property name |
Type |
Default value |
Platforms |
Description |
Required |
Since |
title |
String |
null |
All |
Text that will be displayed at title of message dialog.
|
No |
2 |
message |
String |
null |
All |
Text displayed inside message dialog.
|
Yes |
2 |
imageUrl |
String |
null |
All |
Fully qualified URL of image file that is displayed in message dialog. It should refer to a square PNG or JPEG with preferably at 100x100 pixels size.
|
No |
2 |
positive_button |
String |
null |
Android |
Text that will be displayed at positive button of message dialog.
|
Yes |
3 |
negative_button |
String |
null |
Android |
Text that will be displayed at negative button of message dialog.
|
No |
3 |
Example:
{
"title": "Offer",
"message": "New application is avaliable!",
"imageUrl": "http://example.com/app2-icon.png",
"positive_button": "Install",
"negative_button": "Later"
}