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