Touchgui/plugins/org.apache.cordova.device/doc/index.md

changeset 0
e8ccd40d0ef6
equal deleted inserted replaced
-1:000000000000 0:33f5cf281acd
1 <!---
2 Licensed to the Apache Software Foundation (ASF) under one
3 or more contributor license agreements. See the NOTICE file
4 distributed with this work for additional information
5 regarding copyright ownership. The ASF licenses this file
6 to you under the Apache License, Version 2.0 (the
7 "License"); you may not use this file except in compliance
8 with the License. You may obtain a copy of the License at
9
10 http://www.apache.org/licenses/LICENSE-2.0
11
12 Unless required by applicable law or agreed to in writing,
13 software distributed under the License is distributed on an
14 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 KIND, either express or implied. See the License for the
16 specific language governing permissions and limitations
17 under the License.
18 -->
19
20 # org.apache.cordova.device
21
22 This plugin defines a global `device` object, which describes the device's hardware and software.
23 Although the object is in the global scope, it is not available until after the `deviceready` event.
24
25 document.addEventListener("deviceready", onDeviceReady, false);
26 function onDeviceReady() {
27 console.log(device.cordova);
28 }
29
30 ## Installation
31
32 cordova plugin add org.apache.cordova.device
33
34 ## Properties
35
36 - device.cordova
37 - device.model
38 - device.platform
39 - device.uuid
40 - device.version
41
42 ## device.cordova
43
44 Get the version of Cordova running on the device.
45
46 ### Supported Platforms
47
48 - Amazon Fire OS
49 - Android
50 - BlackBerry 10
51 - Browser
52 - Firefox OS
53 - iOS
54 - Tizen
55 - Windows Phone 7 and 8
56 - Windows 8
57
58 ## device.model
59
60 The `device.model` returns the name of the device's model or
61 product. The value is set by the device manufacturer and may be
62 different across versions of the same product.
63
64 ### Supported Platforms
65
66 - Android
67 - BlackBerry 10
68 - Browser
69 - iOS
70 - Tizen
71 - Windows Phone 7 and 8
72 - Windows 8
73
74 ### Quick Example
75
76 // Android: Nexus One returns "Passion" (Nexus One code name)
77 // Motorola Droid returns "voles"
78 // BlackBerry: Torch 9800 returns "9800"
79 // Browser: Google Chrome returns "Chrome"
80 // Safari returns "Safari"
81 // iOS: for the iPad Mini, returns iPad2,5; iPhone 5 is iPhone 5,1. See http://theiphonewiki.com/wiki/index.php?title=Models
82 //
83 var model = device.model;
84
85 ### Android Quirks
86
87 - Gets the [product name](http://developer.android.com/reference/android/os/Build.html#PRODUCT) instead of the [model name](http://developer.android.com/reference/android/os/Build.html#MODEL), which is often the production code name. For example, the Nexus One returns `Passion`, and Motorola Droid returns `voles`.
88
89 ### Tizen Quirks
90
91 - Returns the device model assigned by the vendor, for example, `TIZEN`
92
93 ### Windows Phone 7 and 8 Quirks
94
95 - Returns the device model specified by the manufacturer. For example, the Samsung Focus returns `SGH-i917`.
96
97 ## device.platform
98
99 Get the device's operating system name.
100
101 var string = device.platform;
102
103 ### Supported Platforms
104
105 - Android
106 - BlackBerry 10
107 - Browser4
108 - Firefox OS
109 - iOS
110 - Tizen
111 - Windows Phone 7 and 8
112 - Windows 8
113
114 ### Quick Example
115
116 // Depending on the device, a few examples are:
117 // - "Android"
118 // - "BlackBerry 10"
119 // - Browser: returns "MacIntel" on Mac
120 // returns "Win32" on Windows
121 // - "iOS"
122 // - "WinCE"
123 // - "Tizen"
124 var devicePlatform = device.platform;
125
126 ### Windows Phone 7 Quirks
127
128 Windows Phone 7 devices report the platform as `WinCE`.
129
130 ### Windows Phone 8 Quirks
131
132 Windows Phone 8 devices report the platform as `Win32NT`.
133
134 ## device.uuid
135
136 Get the device's Universally Unique Identifier ([UUID](http://en.wikipedia.org/wiki/Universally_Unique_Identifier)).
137
138 var string = device.uuid;
139
140 ### Description
141
142 The details of how a UUID is generated are determined by the device manufacturer and are specific to the device's platform or model.
143
144 ### Supported Platforms
145
146 - Android
147 - BlackBerry 10
148 - iOS
149 - Tizen
150 - Windows Phone 7 and 8
151 - Windows 8
152
153 ### Quick Example
154
155 // Android: Returns a random 64-bit integer (as a string, again!)
156 // The integer is generated on the device's first boot
157 //
158 // BlackBerry: Returns the PIN number of the device
159 // This is a nine-digit unique integer (as a string, though!)
160 //
161 // iPhone: (Paraphrased from the UIDevice Class documentation)
162 // Returns a string of hash values created from multiple hardware identifies.
163 // It is guaranteed to be unique for every device and can't be tied
164 // to the user account.
165 // Windows Phone 7 : Returns a hash of device+current user,
166 // if the user is not defined, a guid is generated and will persist until the app is uninstalled
167 // Tizen: returns the device IMEI (International Mobile Equipment Identity or IMEI is a number
168 // unique to every GSM and UMTS mobile phone.
169 var deviceID = device.uuid;
170
171 ### iOS Quirk
172
173 The `uuid` on iOS is not unique to a device, but varies for each
174 application, for each installation. It changes if you delete and
175 re-install the app, and possibly also when you upgrade iOS, or even
176 upgrade the app per version (apparent in iOS 5.1). The `uuid` is not
177 a reliable value.
178
179 ### Windows Phone 7 and 8 Quirks
180
181 The `uuid` for Windows Phone 7 requires the permission
182 `ID_CAP_IDENTITY_DEVICE`. Microsoft will likely deprecate this
183 property soon. If the capability is not available, the application
184 generates a persistent guid that is maintained for the duration of the
185 application's installation on the device.
186
187 ## device.version
188
189 Get the operating system version.
190
191 var string = device.version;
192
193 ### Supported Platforms
194
195 - Android 2.1+
196 - BlackBerry 10
197 - Browser
198 - iOS
199 - Tizen
200 - Windows Phone 7 and 8
201 - Windows 8
202
203 ### Quick Example
204
205 // Android: Froyo OS would return "2.2"
206 // Eclair OS would return "2.1", "2.0.1", or "2.0"
207 // Version can also return update level "2.1-update1"
208 //
209 // BlackBerry: Torch 9800 using OS 6.0 would return "6.0.0.600"
210 //
211 // Browser: Returns version number for the browser
212 //
213 // iPhone: iOS 3.2 returns "3.2"
214 //
215 // Windows Phone 7: returns current OS version number, ex. on Mango returns 7.10.7720
216 // Tizen: returns "TIZEN_20120425_2"
217 var deviceVersion = device.version;
218

mercurial