{"_id":"59031c9a493ed70f004a94a4","parentDoc":null,"project":"5540ce1b31827a0d007ab1cc","__v":0,"category":{"_id":"55a4ff5b2e70c0250038050f","pages":["55a4ff7d750a9a23005332af","55a4ff8b750a9a23005332b1","55a4ff9b750a9a23005332b3","55a60bfcaaf9cf1900114efb","55a6184880c8a30d00b32526","55a61ba780c8a30d00b32532","55a61c97aaf9cf1900114f40","55a61ea9aaf9cf1900114f48","55a6206580c8a30d00b32544","55a64277aaf9cf1900114fc2","55a694d1aaf9cf1900115102","55a6a23eaaf9cf19001151e2","55a6a9b389c9da1900e2a41d","55a6aba45f88a70d0065b255","55a90687c8bd450d000dd157","55af84f3aa902f1700300daa","55afa3e3902fd51700f5f858","55b0cc5cb3171b3700b153fa","56015bdc3aa0520d00da0ced","5603fe3490ee490d004404c2","5633dd18d28a340d004004f5","56448c697a8cb50d00a3ea3f","56d7a2ec5208281500a2506c","56d859b8b159f10b00304577","56d9822add90610b002708a1","56ef44c6e8d6fa17006f244f"],"version":"5540ce1c31827a0d007ab1cf","project":"5540ce1b31827a0d007ab1cc","__v":26,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-07-14T12:23:55.603Z","from_sync":false,"order":2,"slug":"features","title":"Features"},"version":{"_id":"5540ce1c31827a0d007ab1cf","project":"5540ce1b31827a0d007ab1cc","__v":31,"createdAt":"2015-04-29T12:27:08.390Z","releaseDate":"2015-04-29T12:27:08.390Z","categories":["5540ce1c31827a0d007ab1d0","5540d91bbb9e762d00f594ad","5540e5f131827a0d007ab212","5540e5febb9e762d00f594d3","5540e61331827a0d007ab213","5540e6195cf9682100d61afa","5540e62631827a0d007ab214","5540e63031827a0d007ab215","5540e63531827a0d007ab216","5540e63e5cf9682100d61afc","5540e6445cf9682100d61afd","5540e64a5cf9682100d61afe","55a4ff5b2e70c0250038050f","55acb28318eefd0d0071d504","55ae1abe8576b92300291c80","55ae453ef302af23000ac109","55af586d555b900d0036d296","55af91dac8a85321007a53c3","55b9fee204775a2f00628071","55b9ff0e04775a2f00628072","55b9ff4604775a2f00628073","55b9ff5fd72d1e1900276a38","55b9ff7f04775a2f00628074","55b9ff90eb08801900f833e5","55b9ffa5d72d1e1900276a39","55b9ffca04775a2f00628075","55b9fffdd72d1e1900276a3a","56bc2f033ee9e70d008b46af","56c2f6efbbf9ec2d00e0fe4f","57595bbb18760817001e8bbe","57d8d9793916800e003dde53"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"user":"55b125feae3b7621003e6482","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-04-28T10:42:34.926Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":19,"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Check our In-Apps business cases!\",\n  \"body\": \"[Rate My App](https://www.pushwoosh.com/rate-my-app/) - increase 5-star ratings\\n[Net Promoter Score](https://www.pushwoosh.com/article-nps/) - het to know what your users think about your app\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Overview\"\n}\n[/block]\nIn-App messages are notifications that are displayed to a user within the app in response to user interactions. The message itself is deeply customizable as it is based on HTML/CSS/JS, so developers and marketers can make such messages look and feel like a natural part of the application.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/UsXX1btS3KvEPfPmeVzT_iOS_IAM_NPS_example.png\",\n        \"iOS_IAM_NPS_example.png\",\n        \"535\",\n        \"365\",\n        \"#587d92\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nWith In-App messages you can reach all your users, opposed to push notifications that might be delivered only to those who opted-in, which increases the overall audience you can connect with. As In-App messages are displayed based on user behavior and actions performed within the app, they are deeply contextual and relevant to a user while push notifications not always can be triggered with such precision.\n\nOnce properly set up, In-app messages allow you to run deeply personalized promotion campaigns (such as “Rate my app”, Net Promoter Score (NPS) campaigns), effectively interacting with your audience.\n\nThere are three basic steps to create an effective in-app campaign, where you define:\n\n1. What you would like to send. Creative - a HTML page packed as Rich Media which will be shown to a user\n2. When you would like to send it. A specific event to be triggered to receive an In-app\n3. Who you would like to send it to. A segment of users based on Tags and Behavior. \n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Creative\"\n}\n[/block]\nBasically, In-App messages are HTML-based pages that are displayed in a custom web view of the application. An In-App should be compressed to a **.zip** file and comply with the rules below:\n\n- an archive should contain an index.html file in its root folder;\n- all images, CSS and JS files must be included in the .zip archive;\n- you can use remote images in In-Apps, but for iOS they should use *https* protocol unless you add **Allow Arbitrary Loads** to **Info.plist**;\n\nAdd your creative as [Rich Media](http://docs.pushwoosh.com/docs/easy-templates-for-rich-media-with-mailchimp), and then use it as an in-app:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/e6c143b-Pushwoosh___Applications___Pushwoosh_Demo_App___In-Apps.png\",\n        \"Pushwoosh___Applications___Pushwoosh_Demo_App___In-Apps.png\",\n        1147,\n        743,\n        \"#19394d\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Rules\"\n}\n[/block]\nNow as you have the creative, the next step is to create an [Event](doc:events) in your Control Panel as a rule that answers the question \"When the message should be displayed?\"\n\nBasically, an Event is a set of attributes sent from a device (or via Remote API) to Pushwoosh that describes a particular action in an app performed by a user. Events and Event attributes should be first configured in Pushwoosh Control Panel and then should be collected by the SDK when a specific pattern in application is completed. In-App messages are displayed only when a certain event is triggered in the app.\n\nFor example, a \"Login\" event can be triggered when a user logs in using his email address or phone number while connected to Internet via WiFi or cellular network. Then an event can have 2 arguments:\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"\\\"Login credentials\\\"\",\n    \"h-0\": \"Event attributes:\",\n    \"h-1\": \"Attribute type:\",\n    \"0-1\": \"\\\"string\\\"\",\n    \"h-2\": \"Possible values\",\n    \"0-2\": \"\\\"example:::at:::pushwoosh.com\\\", \\\"+1 234 567 89 00\\\" or any other\",\n    \"1-0\": \"\\\"Connection type\\\"\",\n    \"1-1\": \"\\\"string\\\"\",\n    \"1-2\": \"\\\"WiFi\\\" or \\\"cellular\\\"\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\nYou can either set a bare event to trigger an In-App (e.g. show it upon every Login event), or make it specific to the context (e.g. show it only if a login was performed by a user with a particular email address of the Login credentials attribute).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Creating an In-App\"\n}\n[/block]\nOnce you've uploaded a .zip with your creative and set up a triggering Event, you are ready to configure an In-app in the Control Panel. Choose an application you want to receive the In-app and create your first In-app. Give it a name and select your creative from a list of available Rich Media templates. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/dfa711c-select_rich_media.png\",\n        \"select rich media.png\",\n        361,\n        211,\n        \"#222a2e\"\n      ]\n    }\n  ]\n}\n[/block]\nIf a Rich Media is created properly then you will see a preview of an In-app as it should appear on a device.\n\nThe second step is to set a Rule – specify an Event that should trigger your In-app. If there are specific requirements to a triggering Event, you can add more rules covering its attribute values to make your message more personal.\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/6b33f69-specify_event_with_attributes.png\",\n        \"specify event with attributes.png\",\n        1177,\n        291,\n        \"#e0dfe1\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Segmentation\"\n}\n[/block]\nOnce your In-app is set up, you can choose a segment of users who should receive this message. This segmentation includes two parts - Behavior and Tags.\n\n## Behavior\nBehavior segmentation is based on [Events](http://pushwoosh.readme.io/docs/events), i.e. based on actions a user performed while using the app.\nThe example below will target all users who successfully logged in at least 1 time during the last 7 days with their Facebook account.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ZqbVqSlETtOmlCuuxKIm_Pushwoosh___Applications___Demo_application___In-Apps.png\",\n        \"Pushwoosh___Applications___Demo_application___In-Apps.png\",\n        \"472\",\n        \"507\",\n        \"#0fa38a\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n## Tags\nTag segmentation is based on Pushwoosh Tags, such as Country, City, Language, Device model, etc.\nThe example below will narrow the segment to the English locale devices on which the application was opened last time between 1 and 3 days ago range.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/IUdkFXiVSZ6vUGG7MVcV_Pushwoosh___Applications___Demo_application___In-Apps.png\",\n        \"Pushwoosh___Applications___Demo_application___In-Apps.png\",\n        \"664\",\n        \"410\",\n        \"#0a9ce3\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Frequency Capping\"\n}\n[/block]\nYou can use *Frequency Capping* to limit the number of times In-Apps are displayed to the particular user. \n\n- Limit total number of In-App impressions\n- Limit number of impressions in X days\n- Add a delay (in days) between In-App impressions\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/7e7c195-Pushwoosh___Applications___Frequency___In-Apps.png\",\n        \"Pushwoosh___Applications___Frequency___In-Apps.png\",\n        1092,\n        404,\n        \"#41aae0\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"In-app statistics\"\n}\n[/block]\nOnce an In-app is shown to a user, this impression is captured and can be tracked from Pushwoosh Control Panel, allowing you to see In-app statistics in dynamics. This metric is accessible as a counter of total impressions and as a graphics of distribution over a chosen period:\n\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/9b763de-Screen_Shot_2017-05-22_at_13.36.50.png\",\n        \"Screen Shot 2017-05-22 at 13.36.50.png\",\n        867,\n        603,\n        \"#f0f0f0\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"In-App Javascript\"\n}\n[/block]\nIn-Apps are HTML-based and support Javascript. Pushwoosh SDK injects *pushManager* variable that provides the following API:\n\nYou can use *postEvent* method to send a new event directly from In-App Javascript code.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var successCallback = function() {\\n  console.log(\\\"Post event success\\\");\\n}\\n\\nvar errorCallback = function(message) {\\n  console.log(\\\"Post event failed: \\\", message);\\n  alert(\\\"Post event failed: \\\" + message);\\n}\\n\\npushManager.postEvent(JSON.stringify({\\n  \\\"event\\\": \\\"In-app shown\\\",\\n  \\\"attributes\\\": {\\n    \\\"AttributeString\\\": \\\"someString\\\",\\n    \\\"AttributeInt\\\": 42,\\n    \\\"AttributeList\\\": [123, 456, \\\"someString\\\"],\\n    \\\"AttributeBool\\\": true,\\n    \\\"AttributeNull\\\": null,\\n    \\\"AttributeDate\\\": \\\"2015-07-28 19:45\\\" // YYYY-MM-DD hh:mm format\\n  },\\n  \\\"success\\\": \\\"successCallback\\\", // optional\\n  \\\"error\\\": \\\"errorCallback\\\" // optional\\n}));\",\n      \"language\": \"javascript\",\n      \"name\": \"Example:\"\n    }\n  ]\n}\n[/block]\nYou can also use *setTags* method to set tags for the device from an In-App:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"pushManager.sendTags(JSON.stringify({\\n  \\\"IntTag\\\": 42,\\n  \\\"BoolTag\\\": true,\\n  \\\"StringTag\\\": \\\"Some String\\\",\\n  \\\"ListTag\\\": [\\\"string1\\\", \\\"string2\\\"]\\n}));\",\n      \"language\": \"javascript\",\n      \"name\": \"Example\"\n    }\n  ]\n}\n[/block]\nIf you want to close an In-App from the Javascript code call `closeInApp()` method:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"pushManager.closeInApp();\",\n      \"language\": \"javascript\",\n      \"name\": \"Example\"\n    }\n  ]\n}\n[/block]\nOr simply use custom scheme URL for the button/link `<a href=\"pushwoosh://close\">`\n\n## Custom JavaScript interface\n\nIn-App Messages JavaScript functionality can be unlimitedly extended by exposing native Java/Objective-C/Swift methods to JavaScript. This can be achieved with `addJavaScriptInterface` methods of Pushwoosh SDK for [iOS](https://github.com/Pushwoosh/pushwoosh-ios-sdk/blob/master/Documentation/PWInAppManager.md#addjavascriptinterfacewithname) and [Android](https://github.com/Pushwoosh/pushwoosh-android-sdk/blob/master/Documentation/InAppFacade.md#addjavascriptinterface).","excerpt":"","slug":"in-app-messages","type":"basic","title":"In-App Messages"}
[block:callout] { "type": "info", "title": "Check our In-Apps business cases!", "body": "[Rate My App](https://www.pushwoosh.com/rate-my-app/) - increase 5-star ratings\n[Net Promoter Score](https://www.pushwoosh.com/article-nps/) - het to know what your users think about your app" } [/block] [block:api-header] { "type": "basic", "title": "Overview" } [/block] In-App messages are notifications that are displayed to a user within the app in response to user interactions. The message itself is deeply customizable as it is based on HTML/CSS/JS, so developers and marketers can make such messages look and feel like a natural part of the application. [block:image] { "images": [ { "image": [ "https://files.readme.io/UsXX1btS3KvEPfPmeVzT_iOS_IAM_NPS_example.png", "iOS_IAM_NPS_example.png", "535", "365", "#587d92", "" ] } ] } [/block] With In-App messages you can reach all your users, opposed to push notifications that might be delivered only to those who opted-in, which increases the overall audience you can connect with. As In-App messages are displayed based on user behavior and actions performed within the app, they are deeply contextual and relevant to a user while push notifications not always can be triggered with such precision. Once properly set up, In-app messages allow you to run deeply personalized promotion campaigns (such as “Rate my app”, Net Promoter Score (NPS) campaigns), effectively interacting with your audience. There are three basic steps to create an effective in-app campaign, where you define: 1. What you would like to send. Creative - a HTML page packed as Rich Media which will be shown to a user 2. When you would like to send it. A specific event to be triggered to receive an In-app 3. Who you would like to send it to. A segment of users based on Tags and Behavior. [block:api-header] { "type": "basic", "title": "Creative" } [/block] Basically, In-App messages are HTML-based pages that are displayed in a custom web view of the application. An In-App should be compressed to a **.zip** file and comply with the rules below: - an archive should contain an index.html file in its root folder; - all images, CSS and JS files must be included in the .zip archive; - you can use remote images in In-Apps, but for iOS they should use *https* protocol unless you add **Allow Arbitrary Loads** to **Info.plist**; Add your creative as [Rich Media](http://docs.pushwoosh.com/docs/easy-templates-for-rich-media-with-mailchimp), and then use it as an in-app: [block:image] { "images": [ { "image": [ "https://files.readme.io/e6c143b-Pushwoosh___Applications___Pushwoosh_Demo_App___In-Apps.png", "Pushwoosh___Applications___Pushwoosh_Demo_App___In-Apps.png", 1147, 743, "#19394d" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Rules" } [/block] Now as you have the creative, the next step is to create an [Event](doc:events) in your Control Panel as a rule that answers the question "When the message should be displayed?" Basically, an Event is a set of attributes sent from a device (or via Remote API) to Pushwoosh that describes a particular action in an app performed by a user. Events and Event attributes should be first configured in Pushwoosh Control Panel and then should be collected by the SDK when a specific pattern in application is completed. In-App messages are displayed only when a certain event is triggered in the app. For example, a "Login" event can be triggered when a user logs in using his email address or phone number while connected to Internet via WiFi or cellular network. Then an event can have 2 arguments: [block:parameters] { "data": { "0-0": "\"Login credentials\"", "h-0": "Event attributes:", "h-1": "Attribute type:", "0-1": "\"string\"", "h-2": "Possible values", "0-2": "\"example@pushwoosh.com\", \"+1 234 567 89 00\" or any other", "1-0": "\"Connection type\"", "1-1": "\"string\"", "1-2": "\"WiFi\" or \"cellular\"" }, "cols": 3, "rows": 2 } [/block] You can either set a bare event to trigger an In-App (e.g. show it upon every Login event), or make it specific to the context (e.g. show it only if a login was performed by a user with a particular email address of the Login credentials attribute). [block:api-header] { "type": "basic", "title": "Creating an In-App" } [/block] Once you've uploaded a .zip with your creative and set up a triggering Event, you are ready to configure an In-app in the Control Panel. Choose an application you want to receive the In-app and create your first In-app. Give it a name and select your creative from a list of available Rich Media templates. [block:image] { "images": [ { "image": [ "https://files.readme.io/dfa711c-select_rich_media.png", "select rich media.png", 361, 211, "#222a2e" ] } ] } [/block] If a Rich Media is created properly then you will see a preview of an In-app as it should appear on a device. The second step is to set a Rule – specify an Event that should trigger your In-app. If there are specific requirements to a triggering Event, you can add more rules covering its attribute values to make your message more personal. [block:image] { "images": [ { "image": [ "https://files.readme.io/6b33f69-specify_event_with_attributes.png", "specify event with attributes.png", 1177, 291, "#e0dfe1" ] } ] } [/block] [block:api-header] { "title": "Segmentation" } [/block] Once your In-app is set up, you can choose a segment of users who should receive this message. This segmentation includes two parts - Behavior and Tags. ## Behavior Behavior segmentation is based on [Events](http://pushwoosh.readme.io/docs/events), i.e. based on actions a user performed while using the app. The example below will target all users who successfully logged in at least 1 time during the last 7 days with their Facebook account. [block:image] { "images": [ { "image": [ "https://files.readme.io/ZqbVqSlETtOmlCuuxKIm_Pushwoosh___Applications___Demo_application___In-Apps.png", "Pushwoosh___Applications___Demo_application___In-Apps.png", "472", "507", "#0fa38a", "" ] } ] } [/block] ## Tags Tag segmentation is based on Pushwoosh Tags, such as Country, City, Language, Device model, etc. The example below will narrow the segment to the English locale devices on which the application was opened last time between 1 and 3 days ago range. [block:image] { "images": [ { "image": [ "https://files.readme.io/IUdkFXiVSZ6vUGG7MVcV_Pushwoosh___Applications___Demo_application___In-Apps.png", "Pushwoosh___Applications___Demo_application___In-Apps.png", "664", "410", "#0a9ce3", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Frequency Capping" } [/block] You can use *Frequency Capping* to limit the number of times In-Apps are displayed to the particular user. - Limit total number of In-App impressions - Limit number of impressions in X days - Add a delay (in days) between In-App impressions [block:image] { "images": [ { "image": [ "https://files.readme.io/7e7c195-Pushwoosh___Applications___Frequency___In-Apps.png", "Pushwoosh___Applications___Frequency___In-Apps.png", 1092, 404, "#41aae0" ] } ] } [/block] [block:api-header] { "title": "In-app statistics" } [/block] Once an In-app is shown to a user, this impression is captured and can be tracked from Pushwoosh Control Panel, allowing you to see In-app statistics in dynamics. This metric is accessible as a counter of total impressions and as a graphics of distribution over a chosen period: [block:image] { "images": [ { "image": [ "https://files.readme.io/9b763de-Screen_Shot_2017-05-22_at_13.36.50.png", "Screen Shot 2017-05-22 at 13.36.50.png", 867, 603, "#f0f0f0" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "In-App Javascript" } [/block] In-Apps are HTML-based and support Javascript. Pushwoosh SDK injects *pushManager* variable that provides the following API: You can use *postEvent* method to send a new event directly from In-App Javascript code. [block:code] { "codes": [ { "code": "var successCallback = function() {\n console.log(\"Post event success\");\n}\n\nvar errorCallback = function(message) {\n console.log(\"Post event failed: \", message);\n alert(\"Post event failed: \" + message);\n}\n\npushManager.postEvent(JSON.stringify({\n \"event\": \"In-app shown\",\n \"attributes\": {\n \"AttributeString\": \"someString\",\n \"AttributeInt\": 42,\n \"AttributeList\": [123, 456, \"someString\"],\n \"AttributeBool\": true,\n \"AttributeNull\": null,\n \"AttributeDate\": \"2015-07-28 19:45\" // YYYY-MM-DD hh:mm format\n },\n \"success\": \"successCallback\", // optional\n \"error\": \"errorCallback\" // optional\n}));", "language": "javascript", "name": "Example:" } ] } [/block] You can also use *setTags* method to set tags for the device from an In-App: [block:code] { "codes": [ { "code": "pushManager.sendTags(JSON.stringify({\n \"IntTag\": 42,\n \"BoolTag\": true,\n \"StringTag\": \"Some String\",\n \"ListTag\": [\"string1\", \"string2\"]\n}));", "language": "javascript", "name": "Example" } ] } [/block] If you want to close an In-App from the Javascript code call `closeInApp()` method: [block:code] { "codes": [ { "code": "pushManager.closeInApp();", "language": "javascript", "name": "Example" } ] } [/block] Or simply use custom scheme URL for the button/link `<a href="pushwoosh://close">` ## Custom JavaScript interface In-App Messages JavaScript functionality can be unlimitedly extended by exposing native Java/Objective-C/Swift methods to JavaScript. This can be achieved with `addJavaScriptInterface` methods of Pushwoosh SDK for [iOS](https://github.com/Pushwoosh/pushwoosh-ios-sdk/blob/master/Documentation/PWInAppManager.md#addjavascriptinterfacewithname) and [Android](https://github.com/Pushwoosh/pushwoosh-android-sdk/blob/master/Documentation/InAppFacade.md#addjavascriptinterface).