TurkcellUpdater_iOS_sdk

Turkcell Updater for iOS is developed to help developers easily handle new versions of their apps. Easily show new version Popups in ForceUpdate and Optional categories or you can show Messages to users by defining them in a remote Turkcell Updater configuration file. SDK checks version by using "Bundle versions string, short (CFBundleShortVersionString)" property of the application.

Update Request Example

checkUpdateURL The address of the update check url.

preferredLanguageForTitles The preferred language for alertview titles. You can add localization to Localizable.strings file for localization. You can also make customization of the titles using Localizable.strings. Use "nil" to use the default device language.

parentViewController This is used to show the alert controller on the view controller. Use "nil" if you do not want see an alert.

completionHandler Completion handler is the callback of the update check. You will get UpdateAction enum as a response.

    [[UpdaterController sharedInstance] checkUpdateURL:updateURL preferredLanguageForTitles:@"tr" parentViewController:self completionHandler:^(UpdateAction updateAction) {
        if (updateAction == UpdateActionUpdateCheckCompleted) {
            NSLog(@"Update check completed");
        } else if (updateAction == UpdateActionUpdateChosen) {
            NSLog(@"Update action chosen");
        } else if (updateAction == UpdateActionUpdateFound) {//This case is the result of, if there is an update and no parent viewcontroller to show the update message
            NSLog(@"Update action chosen");
        }
    }];    

#####Sample Update Json

{  
   "packageName":"com.turkcell.TurkcellUpdater",
   "updates":[  
      {  
        "filters": {
            "appVersionName":"<=2.7"
        }, 
        "forceUpdate":true,
		"targetWebsiteUrl": "https://itunes.apple.com/tr/app/turkcell-online-kamera/id724524441?mt=8", 
         "descriptions":{  
        	"en":{ 
               "message":"There is a new version.",
               "warnings":"Please update your application."
            },          
            "*":{  
               "message":"Yeni versiyon tespit edildi.",
               "warnings":"Lütfen. Güncelleme yapınız."
            }
         }
      }
   ]
}

Configuration Guide

This documents describes usage and structure configuration files used by Turkcell Updater library.

Usage

Updating an iOS application to a new version served on AppStore

{
	"packageName": "com.turkcell.UpdaterSampleApp",
	"updates": [
		{
			 "descriptions": {
				 "*": {
					 "message": "New version available",
				 }
			 },
			 "targetPackageUrl": "http://appstore.com/turkcell-updater"
		}
	]
}

Forcing an iOS application to update

{
	"packageName": "com.turkcell.UpdaterSampleApp",
	"updates": [
		{
			 "descriptions": {
				 "*": {
					 "message": "New version available",
				 }
			 },
			 "targetPackageUrl": "http://appstore.com/turkcell-updater",
			 "forceUpdate": true,
		}
	]
}

End of support for older iOS OS versions

{
	"packageName": "com.turkcell.UpdaterSampleApp",
	"updates": [
		{
			"filters": {
				"deviceOsVersion": ">=6"
			},
			"descriptions": {
				 "*": {
					 "message": "New version available",
				 }
			},
			"targetPackageUrl": "http://appstore.com/turkcell-updater",
			"forceUpdate": true,
		},
		{
			"filters": {
				"deviceOsVersion": "<6"
			},
		 "descriptions": {
			 "*": {
				 "message": "iOS version earlier than iOS 6 are not supported.",
			 }
		 },
		 "forceUpdate": true,
	}
]

}

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:

iOS

{
	"packageName": "com.turkcell.UpdaterSampleApp",
	"updates": [
		{
			 "descriptions": {
				 "*": {
					 "message": "New version available",
					 "whatIsNew": "Minor bug fixes",
					 "warnings": "New version requires additional privileges"
				 }
			 }
			 "targetPackageUrl": "http://appstore.com/turkcell-updater"
			 "forceUpdate": false
		}
	],
	"messages": [
		{
			"descriptions": {
				"*": {
					"title": "Offer",
					"message": "New application is avaliable!",
					"whatIsNew": "Minor bug fixes",
					"warnings": "New version requires additional privileges"  
				}
			},
			"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
targetPackageUrl	String	null	All	URL of APK package or iTunes link 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
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:

1. 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.
2. On iOS, any update entry should meet at least one of following conditions. Otherwise it will be omitted.
   • forceExit is true
   • targetPackageUrl is not null or empty

Example:

{
	"filters": {
		"appVersionCode": "<10",
		"deviceOsName": "iOS"
	},
	"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"
		}
	},
	"targetPackageUrl": "http://appstore.com/turkcell-updater"
}

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
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:

1. 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:

iOS

{
	"filters": {
		"deviceIsTablet": "true"
	},
	"descriptions": {
		"*": {
			"title": "Offer",
			"message": "New application for your tablet is avaliable!"
		}
	},
	"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
deviceOsName	String	null	All	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
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
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

Example:

{
	"deviceOsName": "iOS",
	"deviceOsVersion": "4.*",
	"appVersionName": "5.0, 5.1, 6.1.*, 7.0.*",
	"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

Example:

{
	"message": "New version available",
	"whatIsNew": "Minor bug fixes",
	"warnings": "New version requires additional privileges"
}

#App Transport Security

With the addition of App Transport Security (ATS) in iOS 9, it is possible to see CFNetwork SSLHandshake failed (-9806) errors. If you run into this problem with Curio SDK requests you can work around this issue by adding the following to your Info.plist. The key "example.com" which is below should be your Curio SDK domain.

	<key>NSAppTransportSecurity</key>		
	<dict>		
		<key>NSExceptionDomains</key>		
		<dict>		
			<key>example.com</key>		
			<dict>		
				<key>NSExceptionAllowsInsecureHTTPLoads</key>		
				<true/>		
				<key>NSExceptionRequiresForwardSecrecy</key>		
				<false/>		
				<key>NSIncludesSubdomains</key>		
				<true/>		
			</dict>		
		</dict>		
	</dict>