Ionic 2 Native Tutorial

Ionic Native is a set of plugins that you can install within your Ionic project, that give you access to native functionality and more.

In Ionic 2, ionic-native is included by default when you use the Ionic CLI to generate a project.

In this tutorial, we're going to discover how to install and use Ionic native plugins.

Setting up a Test Project

If you wish to follow along, make sure you have a new project installed with the Ionic-CLI. If you're following along from the beginning of the free ionic course, you can skip this step.

In the console, type:

$ ionic start geoShow blank

    $ cd geoShow

After it finishes the installation, cd into the geoShow folder.

How to Install an Ionic Native Plugin

Installing a native plugin is made easy with the Ionic-CLI. The format is as follows (don't type this):

ionic plugin add plugin-name
  • ionic: This is how we reference the Ionic-CLI.
  • cordova plugin add: This lets Ionic know that we want to add a plugin.
  • plugin-name: This is the plugin name, which can either be in the form of a plugin ID, a local path, or a Git URL.

When this command is finished running, it places the plugin in the /plugins folder inside of the project root.

How to use an Ionic Native Plugin

After a plugin has been installed, usage is fairly straight forward.

Select the intended component file that will use the plugin, and then we add the plugin as an import:

import {NativePlugin } from '@ionic-native/nativeplugin';

You can add multiple Ionic Native plugins but each will need its own import statement. These native plugins will always be added from @ionic-native.

After a plugin has been imported, you're then free to use it in your component class. The documentation provides you with a Usage example, along with any associated methods and options associated with the plugin.

Let's give it a go

Visit the official Ionic Native documentation, this will provide you with a list of the available native plugins. Let's say for example that we wanted to display a user's current GPS coordinates. We would use the Geolocation plugin.

From the documentation, we can see that it shows us the command for installing it. So let's do that at the console in our project folder:

$ cordova plugin add cordova-plugin-geolocation

We also need to install the Ionic Native package for this plugin. So let's do that at the console in our project folder:

$ npm install --save @ionic-native/geolocation

Next, we head on over to our /src/app/app.modules.ts file and import it at the top too:

import { Geolocation } from '@ionic-native/geolocation';
import { Platform } from 'ionic-angular';

And lastly, we need to add Geolocation to providers too:

Geolocation,

Over at the Geolocation documentation:

It shows us how to use it. In this case, it gives us 2 examples because this plugin has 2 methods (under static members) that we can use: .getCurrentPosition() and .watchPosition(). Let's look at .getCurrentPosition() as an example of how to understand the documentation so we can learn how to use it.

Here we can see that this method accepts options which is described as type GeolocationOptions. We can also see that it Returns a Promise <Geoposition>. Well, what do either of those even mean?

If you scroll down in the documentation further, you'll find sections for both GeolocationOptions and Geoposition

Notice that the GeolocationOptions are all optional, we don't have to pass any of these.

Also, notice that under Geoposition, a type of Coordinates. This is also defined in the documentation:

All of these parameters are returned to us through the coords parameter. This is how we can get a person's location, altitude, speed, etc.. 

In our home.ts file, replace it all with:


import { Component } from '@angular/core';
import { NavController } from 'ionic-angular';
import { Platform } from 'ionic-angular';
import { Geolocation } from '@ionic-native/geolocation';

@Component({
  selector: 'page-home',
  templateUrl: 'home.html'
})
export class HomePage {

      coords2: any;
      accuracy2: any;
      error2: any;

// onSuccess Callback
    // This method accepts a Position object, which contains the
    // current GPS coordinates
    //
    onSuccess (position: any): void {
    console.log("lat:" + position.coords.latitude + "  lon:" +position.coords.longitude);
        alert('Latitude: '          + position.coords.latitude          + '\n' +
              'Longitude: '         + position.coords.longitude         + '\n' +
              'Altitude: '          + position.coords.altitude          + '\n' +
              'Accuracy: '          + position.coords.accuracy          + '\n' +
              'Altitude Accuracy: ' + position.coords.altitudeAccuracy  + '\n' +
              'Heading: '           + position.coords.heading           + '\n' +
              'Speed: '             + position.coords.speed             + '\n' +
              'Timestamp: '         + position.timestamp                + '\n');
          //this.coords2 = position.coords.latitude + ' ' + position.coords.longitude;
          //this.accuracy2 = position.coords.accuracy;
    }

    // onError Callback receives a PositionError object
    //
    onError(error: any): void {
        alert('code: '    + error.code    + '\n' +
        'message: ' + error.message + '\n');
    this.error2 = 'Error getting location: ' + error;
    }

    constructor() {
        this.coords2 = '';
        this.accuracy2 = '';

    }

    watch() {
    navigator.geolocation.getCurrentPosition(this.onSuccess, this.onError);
    }
}

So, we're defining 3 properties coords2, accuracy2, and error2. Then, we're creating a watch() method uses the getCurrentPosition() method of Geolocation.

If it's successful, we define coords2 and accuracy2 to the response. Per the documentation, we know that the response will contain a coords object with .latitude, .accuracy, and others.

In the home.html template, paste in this HTML:

<ion-card>
      <ion-card-content>
        <button ion-button (click)="watch()">Get Position</button>
        <!--
        <p>Position: {{ coords2 }}</p>
        <p>Accuracy: {{ accuracy2 }} meters</p>
        -->
        <p *ngIf="error">{{ error2 }}</p>
      </ion-card-content>
    </ion-card>

In the console, type:

$ ionic serve -l

This gives us the following result:

The accuracy is really off, likely because I'm on a desktop. If you want to preview it on your phone, you will need to use the ionic run device (device could either be android or ios). 

On my android phone, the accuracy is 18 meters.

How to Remove an Ionic Native Plugin

You may find that during the course of development, that you may amass a bunch of unused plugins.

After removing any references to the plugin in your code, in the console type:

$ ionic plugin remove plugin-name

This will remove the plugin folder from /plugins as well as from any devices that have been added to the project.