{"_id":"56d31b848161a00b00dc458a","project":"5526c95cf69851170038b48f","user":"5526ca4cf69851170038b496","category":{"_id":"56d1f33900a2a70b00b36593","__v":2,"project":"5526c95cf69851170038b48f","version":"56d1f33700a2a70b00b3658e","pages":["56d1f33a00a2a70b00b365aa","56d1f33a00a2a70b00b365ab","56d1f33a00a2a70b00b365ac","56d1f33a00a2a70b00b365ad","56d1f33a00a2a70b00b365ae","56d1f33a00a2a70b00b365af","56d1f33a00a2a70b00b365b0","56d1f33a00a2a70b00b365b1","56d1f33a00a2a70b00b365b2","56d1f33a00a2a70b00b365b3","56d1f33a00a2a70b00b365b4","56d1f33a00a2a70b00b365b5","56d1f33a00a2a70b00b365b6","56d1f33a00a2a70b00b365b7","56d1f33a00a2a70b00b365b8","56d1f33a00a2a70b00b365b9","56d1f33a00a2a70b00b365ba","56d1f33a00a2a70b00b365bb","56d1f33a00a2a70b00b365bc","56d1f33a00a2a70b00b365bd","56d1f33a00a2a70b00b365be","56d1f33a00a2a70b00b365bf","56d1f33a00a2a70b00b365c0","56d31b848161a00b00dc458a"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-04-10T15:00:49.659Z","from_sync":false,"order":3,"slug":"ionic-push","title":"Ionic Push"},"version":{"_id":"56d1f33700a2a70b00b3658e","project":"5526c95cf69851170038b48f","__v":2,"createdAt":"2016-02-27T19:04:23.946Z","releaseDate":"2016-02-27T19:04:23.946Z","categories":["56d1f33900a2a70b00b3658f","56d1f33900a2a70b00b36590","56d1f33900a2a70b00b36591","56d1f33900a2a70b00b36592","56d1f33900a2a70b00b36593","56d1f33900a2a70b00b36594","56d1f33900a2a70b00b36595","56d1f33900a2a70b00b36596","56d1f33900a2a70b00b36597","56d1f33900a2a70b00b36598","56d1f33900a2a70b00b36599","56d1f33900a2a70b00b3659a","571f9497ada30c34003b7cee"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"beta","version_clean":"2.0.0-beta","version":"2.0.0-beta"},"__v":20,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-28T16:08:36.215Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/DwctiXvRQKWoXT0Ma5xI_send-push-diagram.png\",\n        \"send-push-diagram.png\",\n        \"2075\",\n        \"772\",\n        \"#4181b1\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\nThe diagram above gives you a high level overview of how a notification is delivered to a user's device, but let's talk a little more in-depth about what components are actually involved to send a notification to a device.\n\nFirst, you'll need to setup an account with Apple, Google, or both depending on the target devices you wish to deliver to. If you're reading these docs, you likely already have accounts setup for your target platforms.\n\nWith an account setup, you'll have access to generate a push-enabled certificate and mobile provisioning profile for iOS devices, or access to a Google Cloud Messaging project where you can an API Key and Project Number for the Android devices.\n\nIn order for us to communicate to APNs or GCM on your behalf, we'll need to store the details from the previous step. We store these details in what we call a *Security Profile*. You can end up creating more than one profile to use across different environments. It would be common for you to have one profile setup with \"development\" credentials, and another meant for \"production\" usage. We'll dive more into that in a bit.\n\nOnce you have a security profile created, you can install and configure the necessary components that will ultimately allow you to register your device to receive push notifications. After that, the only thing left to do is send a push notification to your device!\n\nIt might seem like a lot to take in at first glance, but don't worry, it's actually quite easy, and we'll walk you through each step in the following sections:\n\n* [1. Account Creation](#1-account-creation)\n* [2. Security Profile](#2-security-profile)\n* [3. App Setup](#3-app-setup)\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"1. Account Creation\"\n}\n[/block]\nMore than likely you already have accounts created, but if you haven't already, you'll need to setup an [Apple Developer Account](https://developer.apple.com/programs/enroll/) if you plan to send to iOS devices. If you plan to send to Android devices, you'll need to setup a [Google Account](https://accounts.google.com/SignUp).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"2. Security Profile\"\n}\n[/block]\nThe following guides will help you setup a security profile for use with push, but it's worth mentioning that if you plan to create a profile for both iOS and Android devices, you can use a single profile for both.\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"This step is crucial so *please* read the linked guides carefully. Mistakes in this section will likely result in an app that cannot receive notifications.\"\n}\n[/block]\n## 2.1 iOS Details\n\nIf you're sending to Apple devices, you'll need to generate a certificate and provisioning profile. The certificate allows us to communicate with APNs on your behalf, and the provisioning profile ensures that your device is allowed to work with the generated certificate. We're simplifying that quite a bit, but that's the gist.\n\nFollow the [iOS Push Profiles](doc:ios-push-profiles) guide to configure push for APNs. \n\n## 2.2 Android Details\n\nIf you're sending to Android devices, you'll need to create a project in the Google Developer Console and enable the Google Cloud Messaging (GCM) API. This will give you access to an API Key that allows us to communicate with GCM on your behalf, and the project number is used to associate your device with that project.\n\nFollow the [Android Push Profiles](doc:android-push-profiles) guide to configure push for GCM.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"3. App Setup\"\n}\n[/block]\n\n## 3.1 Create an app\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"ionic start myApp tabs\\ncd myApp\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n## 3.2 Install the necessary components\n\nWe need some code to let your app talk to the Ionic Platform, as well as a Cordova plugin to implement native push notifications within your app.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"ionic add ionic-platform-web-client\\nionic plugin add phonegap-plugin-push --variable SENDER_ID=\\\"GCM_PROJECT_NUMBER\\\"\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Plugin Updates\",\n  \"body\": \"The latest plugin update requires that a `SENDER_ID` variable be set for Android. That is actually your GCM Project Number. If you're not using Android, you'll just need to pass a random string (you could even use the above command as-is).\"\n}\n[/block]\n\n## 3.3 Hook up with ionic.io\n\nRunning the following command to identify your app with Ionic.  \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"ionic io init\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n## 3.4 Disable *limited pushes*\n\nAs you may already know from the push overview, we default your app to use limited push functionality using the `dev_push` [config](doc:io-config) property. Now that we're ready to use full-featured pushes, we will disable limited pushes:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"ionic config set dev_push false\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n## 3.5 Add some push code\n\nOk, we're all configured and ready to write some push code!  All you need to do to get your app receiving notifications is add the following snippet somewhere.  To ensure that it's always registered, we're going to put in inside the `$ionicPlatform.ready()` section within our `app.js` file.  This will create an instance of the push service and register your app for notifications each time it is opened.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \".run(function($ionicPlatform) {\\n  $ionicPlatform.ready(function() {\\n    var push = new Ionic.Push({\\n      \\\"debug\\\": true\\n    });\\n\\n    push.register(function(token) {\\n      console.log(\\\"Device token:\\\",token.token);\\n      push.saveToken(token);  // persist the token in the Ionic Platform\\n    });\\n  });\\n})\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n## 3.6 Send a push!\n\nIn order to send a push via the API, you'll need to create an API token to use authorize with the API (follow [this guide](doc:api-getting-started#section-creating-a-token) to get a token for your app), and you'll need a device token that you registered in the previous step. \n\nYou'll also need the *tag* of the security profile you generated in step 2.\n\nOnce you have the required information, replace the highlighted text with your own values in the cURL request below:\n[block:html]\n{\n  \"html\": \"<div class=\\\"curl-example\\\">\\n<pre>\\ncurl -X POST -H \\\"Authorization: Bearer <span class=\\\"hlite\\\">API_TOKEN</span>\\\" -H \\\"Content-Type: application/json\\\" -d '{\\n    \\\"tokens\\\": [\\\"<span class=\\\"hlite\\\">DEV_DEVICE_TOKEN</span>\\\"],\\n    \\\"profile\\\": \\\"<span class=\\\"hlite\\\">PROFILE_TAG</span>\\\",\\n    \\\"notification\\\": {\\n        \\\"message\\\": \\\"Hello World!\\\"\\n    }\\n}' \\\"https://api.ionic.io/push/notifications\\\"\\n</pre>\\n</div>\\n\\n<style>\\n  \\nspan.hlite {\\n  font-weight: bold;\\n  color: #0000FF;\\n}\\n  \\n.curl-example pre {\\n  padding: 16px;\\n  border: 0px solid #fff;\\n  font-size: 11px !important;\\n  color: #444;\\n}\\n</style>\"\n}\n[/block]\nIf you want to see the classic notification show up in your notifications area, you need to make sure that your application is *closed* or in the *background*. Your notification will still be received while the application is open, but it will not show up in the class shade area, instead it will just call your `onNotification` handler.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Congratulations!\",\n  \"body\": \"If everything has been configured correctly, you should have received a push notification on your device. You are now ready to dive into the full set of configuration options available with the API which you can learn about in the [Sending Push](doc:push-sending-push).\"\n}\n[/block]","excerpt":"Configure full featured push notifications that utilize APNs and/or GCM","slug":"push-full-setup","type":"basic","title":"Full Setup"}

Full Setup

Configure full featured push notifications that utilize APNs and/or GCM

[block:image] { "images": [ { "image": [ "https://files.readme.io/DwctiXvRQKWoXT0Ma5xI_send-push-diagram.png", "send-push-diagram.png", "2075", "772", "#4181b1", "" ] } ] } [/block] The diagram above gives you a high level overview of how a notification is delivered to a user's device, but let's talk a little more in-depth about what components are actually involved to send a notification to a device. First, you'll need to setup an account with Apple, Google, or both depending on the target devices you wish to deliver to. If you're reading these docs, you likely already have accounts setup for your target platforms. With an account setup, you'll have access to generate a push-enabled certificate and mobile provisioning profile for iOS devices, or access to a Google Cloud Messaging project where you can an API Key and Project Number for the Android devices. In order for us to communicate to APNs or GCM on your behalf, we'll need to store the details from the previous step. We store these details in what we call a *Security Profile*. You can end up creating more than one profile to use across different environments. It would be common for you to have one profile setup with "development" credentials, and another meant for "production" usage. We'll dive more into that in a bit. Once you have a security profile created, you can install and configure the necessary components that will ultimately allow you to register your device to receive push notifications. After that, the only thing left to do is send a push notification to your device! It might seem like a lot to take in at first glance, but don't worry, it's actually quite easy, and we'll walk you through each step in the following sections: * [1. Account Creation](#1-account-creation) * [2. Security Profile](#2-security-profile) * [3. App Setup](#3-app-setup) [block:api-header] { "type": "basic", "title": "1. Account Creation" } [/block] More than likely you already have accounts created, but if you haven't already, you'll need to setup an [Apple Developer Account](https://developer.apple.com/programs/enroll/) if you plan to send to iOS devices. If you plan to send to Android devices, you'll need to setup a [Google Account](https://accounts.google.com/SignUp). [block:api-header] { "type": "basic", "title": "2. Security Profile" } [/block] The following guides will help you setup a security profile for use with push, but it's worth mentioning that if you plan to create a profile for both iOS and Android devices, you can use a single profile for both. [block:callout] { "type": "danger", "body": "This step is crucial so *please* read the linked guides carefully. Mistakes in this section will likely result in an app that cannot receive notifications." } [/block] ## 2.1 iOS Details If you're sending to Apple devices, you'll need to generate a certificate and provisioning profile. The certificate allows us to communicate with APNs on your behalf, and the provisioning profile ensures that your device is allowed to work with the generated certificate. We're simplifying that quite a bit, but that's the gist. Follow the [iOS Push Profiles](doc:ios-push-profiles) guide to configure push for APNs. ## 2.2 Android Details If you're sending to Android devices, you'll need to create a project in the Google Developer Console and enable the Google Cloud Messaging (GCM) API. This will give you access to an API Key that allows us to communicate with GCM on your behalf, and the project number is used to associate your device with that project. Follow the [Android Push Profiles](doc:android-push-profiles) guide to configure push for GCM. [block:api-header] { "type": "basic", "title": "3. App Setup" } [/block] ## 3.1 Create an app [block:code] { "codes": [ { "code": "ionic start myApp tabs\ncd myApp", "language": "shell" } ] } [/block] ## 3.2 Install the necessary components We need some code to let your app talk to the Ionic Platform, as well as a Cordova plugin to implement native push notifications within your app. [block:code] { "codes": [ { "code": "ionic add ionic-platform-web-client\nionic plugin add phonegap-plugin-push --variable SENDER_ID=\"GCM_PROJECT_NUMBER\"", "language": "shell" } ] } [/block] [block:callout] { "type": "danger", "title": "Plugin Updates", "body": "The latest plugin update requires that a `SENDER_ID` variable be set for Android. That is actually your GCM Project Number. If you're not using Android, you'll just need to pass a random string (you could even use the above command as-is)." } [/block] ## 3.3 Hook up with ionic.io Running the following command to identify your app with Ionic. [block:code] { "codes": [ { "code": "ionic io init", "language": "shell" } ] } [/block] ## 3.4 Disable *limited pushes* As you may already know from the push overview, we default your app to use limited push functionality using the `dev_push` [config](doc:io-config) property. Now that we're ready to use full-featured pushes, we will disable limited pushes: [block:code] { "codes": [ { "code": "ionic config set dev_push false", "language": "shell" } ] } [/block] ## 3.5 Add some push code Ok, we're all configured and ready to write some push code! All you need to do to get your app receiving notifications is add the following snippet somewhere. To ensure that it's always registered, we're going to put in inside the `$ionicPlatform.ready()` section within our `app.js` file. This will create an instance of the push service and register your app for notifications each time it is opened. [block:code] { "codes": [ { "code": ".run(function($ionicPlatform) {\n $ionicPlatform.ready(function() {\n var push = new Ionic.Push({\n \"debug\": true\n });\n\n push.register(function(token) {\n console.log(\"Device token:\",token.token);\n push.saveToken(token); // persist the token in the Ionic Platform\n });\n });\n})", "language": "javascript" } ] } [/block] ## 3.6 Send a push! In order to send a push via the API, you'll need to create an API token to use authorize with the API (follow [this guide](doc:api-getting-started#section-creating-a-token) to get a token for your app), and you'll need a device token that you registered in the previous step. You'll also need the *tag* of the security profile you generated in step 2. Once you have the required information, replace the highlighted text with your own values in the cURL request below: [block:html] { "html": "<div class=\"curl-example\">\n<pre>\ncurl -X POST -H \"Authorization: Bearer <span class=\"hlite\">API_TOKEN</span>\" -H \"Content-Type: application/json\" -d '{\n \"tokens\": [\"<span class=\"hlite\">DEV_DEVICE_TOKEN</span>\"],\n \"profile\": \"<span class=\"hlite\">PROFILE_TAG</span>\",\n \"notification\": {\n \"message\": \"Hello World!\"\n }\n}' \"https://api.ionic.io/push/notifications\"\n</pre>\n</div>\n\n<style>\n \nspan.hlite {\n font-weight: bold;\n color: #0000FF;\n}\n \n.curl-example pre {\n padding: 16px;\n border: 0px solid #fff;\n font-size: 11px !important;\n color: #444;\n}\n</style>" } [/block] If you want to see the classic notification show up in your notifications area, you need to make sure that your application is *closed* or in the *background*. Your notification will still be received while the application is open, but it will not show up in the class shade area, instead it will just call your `onNotification` handler. [block:callout] { "type": "success", "title": "Congratulations!", "body": "If everything has been configured correctly, you should have received a push notification on your device. You are now ready to dive into the full set of configuration options available with the API which you can learn about in the [Sending Push](doc:push-sending-push)." } [/block]