0
# Ionic Native
1
2
Ionic Native provides a comprehensive collection of TypeScript wrappers for Cordova plugins, enabling native mobile functionality in Ionic, Cordova, and web view applications. It standardizes native functionality access through Promise and Observable interfaces while maintaining compatibility with both Angular 1 and Angular 2+ applications.
3
4
## Package Information
5
6
- **Package Name**: ionic-native
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install ionic-native`
10
- **Dependencies**: RxJS 5.0.1
11
12
## Core Imports
13
14
```typescript
15
import { Camera, Device, Geolocation } from 'ionic-native';
16
```
17
18
For CommonJS:
19
20
```javascript
21
const { Camera, Device, Geolocation } = require('ionic-native');
22
```
23
24
Browser global access:
25
26
```javascript
27
// Available as window.IonicNative after including the bundle
28
window.IonicNative.Camera.getPicture(options);
29
```
30
31
## Basic Usage
32
33
```typescript
34
import { Camera, CameraOptions } from 'ionic-native';
35
36
// Configure camera options
37
const options: CameraOptions = {
38
quality: 100,
39
destinationType: Camera.DestinationType.FILE_URI,
40
sourceType: Camera.PictureSourceType.CAMERA,
41
encodingType: Camera.EncodingType.JPEG,
42
targetWidth: 300,
43
targetHeight: 300
44
};
45
46
// Take a picture
47
Camera.getPicture(options).then((imageData) => {
48
// imageData is either a base64 encoded string or a file URI
49
let base64Image = 'data:image/jpeg;base64,' + imageData;
50
}, (err) => {
51
// Handle error
52
});
53
```
54
55
## Architecture
56
57
Ionic Native is built around several key architectural patterns:
58
59
- **Plugin Wrapper Pattern**: All plugins extend from base plugin infrastructure with TypeScript decorators
60
- **Promise-based API**: Most async operations return native Promises with Angular $q integration
61
- **Observable Support**: Event-based operations use RxJS Observables for reactive programming
62
- **Static Method Pattern**: Primary API surface uses static methods on plugin classes
63
- **Runtime Checking**: Automatic plugin availability and Cordova environment validation
64
- **Cross-platform**: Unified API across iOS, Android, Windows, and Browser platforms
65
66
## Capabilities
67
68
### Device & System Information
69
70
Core device information and system capabilities for identifying device characteristics and platform details.
71
72
```typescript { .api }
73
class Device {
74
static cordova: string;
75
static model: string;
76
static platform: string;
77
static uuid: string;
78
static version: string;
79
static manufacturer: string;
80
static isVirtual: boolean;
81
static serial: string;
82
}
83
84
class AppVersion {
85
static getAppName(): Promise<string>;
86
static getPackageName(): Promise<string>;
87
static getVersionCode(): Promise<string | number>;
88
static getVersionNumber(): Promise<string>;
89
}
90
```
91
92
[Device & System](./device-system.md)
93
94
### Camera & Media Capture
95
96
Comprehensive camera functionality, media capture, and photo/video management with full configuration options.
97
98
```typescript { .api }
99
interface CameraOptions {
100
quality?: number;
101
destinationType?: number;
102
sourceType?: number;
103
allowEdit?: boolean;
104
encodingType?: number;
105
targetWidth?: number;
106
targetHeight?: number;
107
mediaType?: number;
108
correctOrientation?: boolean;
109
saveToPhotoAlbum?: boolean;
110
cameraDirection?: number;
111
popoverOptions?: CameraPopoverOptions;
112
}
113
114
class Camera {
115
static getPicture(options?: CameraOptions): Promise<any>;
116
static cleanup(): Promise<any>;
117
static DestinationType: {
118
DATA_URL: 0;
119
FILE_URI: 1;
120
NATIVE_URI: 2;
121
};
122
static EncodingType: {
123
JPEG: 0;
124
PNG: 1;
125
};
126
}
127
```
128
129
[Camera & Media](./camera-media.md)
130
131
### Storage & File Management
132
133
File system operations, database access, and secure storage solutions for mobile app data persistence.
134
135
```typescript { .api }
136
class File {
137
static applicationDirectory: string;
138
static dataDirectory: string;
139
static cacheDirectory: string;
140
static externalDataDirectory: string;
141
static createFile(path: string, fileName: string, replace: boolean): Promise<FileEntry>;
142
static writeFile(path: string, fileName: string, text: string | Blob | ArrayBuffer, options: IWriteOptions): Promise<any>;
143
static readAsText(path: string, file: string): Promise<string>;
144
static removeFile(path: string, fileName: string): Promise<RemoveResult>;
145
}
146
147
class SQLite {
148
static create(config: any): SQLiteObject;
149
}
150
```
151
152
[Storage & Files](./storage-files.md)
153
154
### Network & Communication
155
156
HTTP requests, network status monitoring, and in-app browser functionality for connected applications.
157
158
```typescript { .api }
159
interface HTTPResponse {
160
status: number;
161
data?: any;
162
headers: any;
163
url: string;
164
}
165
166
class HTTP {
167
static get(url: string, parameters: any, headers: any): Promise<HTTPResponse>;
168
static post(url: string, body: any, headers: any): Promise<HTTPResponse>;
169
static put(url: string, body: any, headers: any): Promise<HTTPResponse>;
170
static delete(url: string, parameters: any, headers: any): Promise<HTTPResponse>;
171
}
172
173
class Network {
174
static type: string;
175
static onConnect(): Observable<any>;
176
static onDisconnect(): Observable<any>;
177
}
178
```
179
180
[Network & Communication](./network-communication.md)
181
182
### Location & Maps
183
184
Geolocation services, background location tracking, and geofencing capabilities for location-aware applications.
185
186
```typescript { .api }
187
interface GeolocationOptions {
188
enableHighAccuracy?: boolean;
189
timeout?: number;
190
maximumAge?: number;
191
}
192
193
interface Geoposition {
194
coords: Coordinates;
195
timestamp: number;
196
}
197
198
class Geolocation {
199
static getCurrentPosition(options?: GeolocationOptions): Promise<Geoposition>;
200
static watchPosition(options?: GeolocationOptions): Observable<Geoposition>;
201
}
202
```
203
204
[Location & Maps](./location-maps.md)
205
206
### Notifications & UI
207
208
Push notifications, local notifications, dialogs, and UI interaction components for user engagement.
209
210
```typescript { .api }
211
interface ILocalNotification {
212
id?: number;
213
title?: string;
214
text?: string;
215
every?: string;
216
at?: Date;
217
data?: any;
218
}
219
220
class LocalNotifications {
221
static schedule(options?: ILocalNotification | ILocalNotification[]): void;
222
static clear(notificationId: number): Promise<boolean>;
223
static on(eventName: string): Observable<any>;
224
}
225
226
class Toast {
227
static show(message: string, duration: string, position: string): Promise<any>;
228
static showShortTop(message: string): Promise<any>;
229
}
230
```
231
232
[Notifications & UI](./notifications-ui.md)
233
234
### Device Sensors
235
236
Access to device sensors including accelerometer, gyroscope, compass, battery status, and vibration.
237
238
```typescript { .api }
239
interface Acceleration {
240
x: number;
241
y: number;
242
z: number;
243
timestamp: number;
244
}
245
246
class DeviceMotion {
247
static getCurrentAcceleration(): Promise<Acceleration>;
248
static watchAcceleration(options?: AccelerometerOptions): Observable<Acceleration>;
249
}
250
251
class Vibration {
252
static vibrate(time: number | number[]): void;
253
}
254
```
255
256
[Device Sensors](./device-sensors.md)
257
258
### Social & Sharing
259
260
Social media integration, content sharing, and authentication for Facebook, Google+, and Twitter platforms.
261
262
```typescript { .api }
263
class SocialSharing {
264
static share(message?: string, subject?: string, file?: string | string[], url?: string): Promise<any>;
265
static shareViaEmail(message: string, subject: string, to: string[], cc?: string[], bcc?: string[], files?: string | string[]): Promise<any>;
266
static shareViaTwitter(message: string, image?: string, url?: string): Promise<any>;
267
}
268
269
interface FacebookLoginResponse {
270
status: string;
271
authResponse: {
272
userID: string;
273
accessToken: string;
274
};
275
}
276
277
class Facebook {
278
static login(permissions: string[]): Promise<FacebookLoginResponse>;
279
}
280
```
281
282
[Social & Sharing](./social-sharing.md)
283
284
### Security & Authentication
285
286
Biometric authentication, secure storage, and device security features for protecting user data.
287
288
```typescript { .api }
289
class TouchID {
290
static isAvailable(): Promise<string>;
291
static verifyFingerprint(message: string): Promise<any>;
292
}
293
294
interface FingerprintOptions {
295
clientId: string;
296
clientSecret: string;
297
disableBackup?: boolean;
298
}
299
300
class FingerprintAIO {
301
static isAvailable(): Promise<any>;
302
static show(options: FingerprintOptions): Promise<any>;
303
}
304
```
305
306
[Security & Authentication](./security-auth.md)
307
308
### Input & Hardware
309
310
Barcode scanning, NFC communication, keyboard management, and hardware interaction capabilities.
311
312
```typescript { .api }
313
interface BarcodeScannerOptions {
314
preferFrontCamera?: boolean;
315
showFlipCameraButton?: boolean;
316
showTorchButton?: boolean;
317
torchOn?: boolean;
318
prompt?: string;
319
resultDisplayDuration?: number;
320
formats?: string;
321
orientation?: string;
322
disableAnimations?: boolean;
323
disableSuccessBeep?: boolean;
324
}
325
326
interface BarcodeScanResult {
327
text: string;
328
format: string;
329
cancelled: boolean;
330
}
331
332
class BarcodeScanner {
333
static scan(options?: BarcodeScannerOptions): Promise<BarcodeScanResult>;
334
}
335
```
336
337
[Input & Hardware](./input-hardware.md)
338
339
### Analytics & Monetization
340
341
App analytics, advertising integration, and monetization features for tracking user behavior and revenue generation.
342
343
```typescript { .api }
344
interface AdMobOptions {
345
bannerId?: string;
346
interstitialId?: string;
347
rewardVideoId?: string;
348
isTesting?: boolean;
349
autoShow?: boolean;
350
}
351
352
class AdMob {
353
static createBanner(adIdOrOptions: string | AdMobOptions): Promise<any>;
354
static showInterstitial(): Promise<any>;
355
}
356
357
class GoogleAnalytics {
358
static startTrackerWithId(id: string): Promise<any>;
359
static trackView(title: string): Promise<any>;
360
static trackEvent(category: string, action: string, label?: string, value?: number): Promise<any>;
361
}
362
```
363
364
[Analytics & Monetization](./analytics-monetization.md)
365
366
## Core Infrastructure
367
368
### Plugin Decorator System
369
370
```typescript { .api }
371
interface PluginConfig {
372
pluginName: string;
373
plugin: string;
374
pluginRef: string;
375
repo: string;
376
install?: string;
377
platforms?: string[];
378
}
379
380
interface CordovaOptions {
381
sync?: boolean;
382
observable?: boolean;
383
callbackOrder?: 'reverse';
384
callbackStyle?: 'node' | 'object';
385
successIndex?: number;
386
errorIndex?: number;
387
platforms?: string[];
388
}
389
390
// TypeScript decorators for plugin method wrapping
391
function Plugin(config: PluginConfig): ClassDecorator;
392
function Cordova(opts?: CordovaOptions): MethodDecorator;
393
function CordovaInstance(opts?: any): MethodDecorator;
394
function CordovaProperty(target: any, key: string): void;
395
```
396
397
## Types
398
399
```typescript { .api }
400
// Core utility types used across plugins
401
interface RemoveResult {
402
success: boolean;
403
fileRemoved: Entry;
404
}
405
406
interface Entry {
407
isFile: boolean;
408
isDirectory: boolean;
409
name: string;
410
fullPath: string;
411
}
412
413
interface FileEntry extends Entry {
414
file(successCallback: (file: File) => void, errorCallback?: (error: FileError) => void): void;
415
}
416
417
interface DirectoryEntry extends Entry {
418
createReader(): DirectoryReader;
419
getFile(path: string, options?: Flags, successCallback?: (entry: FileEntry) => void, errorCallback?: (error: FileError) => void): void;
420
getDirectory(path: string, options?: Flags, successCallback?: (entry: DirectoryEntry) => void, errorCallback?: (error: FileError) => void): void;
421
}
422
423
// Promise/Observable type patterns
424
type CordovaPromise<T> = Promise<T>;
425
type CordovaObservable<T> = Observable<T>;
426
```