{"__v":10,"_id":"55ecd6edae66a30d00446ce7","category":{"__v":35,"_id":"55e67b5556007d23005fee7d","pages":["55e67b91de6fef23009480cb","55e67c28de6fef23009480ce","55e67c3cde6fef23009480d1","55e680e185a9741900314e96","55e682b7de6fef23009480dc","55ecd69bb2714d2100f227c0","55ecd6c554a67b1700edcf40","55ecd6edae66a30d00446ce7","55ecd777b2714d2100f227c2","55ecda5a7659d21700a7ef9b","55ecdaf6ae66a30d00446cf3","55ed006a0d968e2100de831e","55ed0258c9d5b3350072ae7a","55ee66a073d3941700f760e5","55f5ef61a1dea80d00a5dec5","55f5f38618b39b0d00c27eb0","55f9f86417b9d00d00969e29","55f9fdc8aba81f0d00a1156d","561b10b4c89cc30d0082154f","561b110a03bce90d00c4bd11","561c6195ad272c0d00a892dd","561c6ca0be5fb20d00077754","564f3e66c133343500286ca0","565b955b922c9a0d00d1f124","566784d2919aaa0d008e32db","566e1ee5972a290d00552084","569c58d77c3e44170014114f","56a2692f6928550d006c8327","56ca6c868014e417002bfe54","56cfa5386c5d7a13005eec0f","56e73d86555c030e00a52a73","56e7460c9000b120000ffe2e","56e8c19e99c6400e003820cf","56e8c53fc88bf80e00f8bed8","56f06ff4d386ce0e008e9b21"],"project":"55e67aaa9cc7c62b00c4a1ea","version":"55e67aab9cc7c62b00c4a1ed","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-09-02T04:30:13.305Z","from_sync":false,"order":1,"slug":"install-in-your-app","title":"Install in your app"},"parentDoc":null,"project":"55e67aaa9cc7c62b00c4a1ea","user":"55d2bd8e2463351700f67dd7","version":{"__v":10,"_id":"55e67aab9cc7c62b00c4a1ed","project":"55e67aaa9cc7c62b00c4a1ea","createdAt":"2015-09-02T04:27:23.612Z","releaseDate":"2015-09-02T04:27:23.612Z","categories":["55e67aac9cc7c62b00c4a1ee","55e67b5556007d23005fee7d","55e67b5dde6fef23009480ca","55e680efde6fef23009480db","55e6829485a9741900314e99","561c61b4ad272c0d00a892df","586c014c0abf1d0f000d04d4","58991d2ad207df0f0002186b","589b8e1fdbb7cd190026732c","58b8ca5e3265d70f001788d4"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-07T00:14:37.434Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":true,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":9,"body":"Carnival supports a [Cordova](https://cordova.apache.org/) plugin that allows you to use the Carnival SDK for iOS and Android through a JavaScript interface.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Cordova minimum version\",\n  \"body\": \"Carnival supports the following plugins:\\n* `carnival-cli` version 6.5.0 or later\\n* `cordova-platform-ios` version 4.1.1 or later\\n* `cordova-platform-android` version 6.0.0 or later\\n\\nAlthough Carnival may compile on with earlier versions, it may lead to unforeseen issues.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Installation\"\n}\n[/block]\nThis guide assumes Cordova is installed in your machine and your project is already initialized.\n\n## Add the plugin\nType the following command inside your project directory:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"cordova plugin add https://github.com/carnivalmobile/carnival-sdk-cordova.git\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n## Add the SDK Key\n\nAdd a preference to your `config.xml` file with your Carnival App key (from [http://app.carnivalmobile.com](http://app.carnivalmobile.com)).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<platform name=\\\"ios\\\">\\n    <preference name=\\\"carnival_ios_app_key\\\" value=\\\"YOUR_APP_KEY_GOES_HERE\\\" />\\n</platform>\",\n      \"language\": \"xml\",\n      \"name\": \"iOS\"\n    },\n    {\n      \"code\": \"<platform name=\\\"android\\\">\\n    <preference name=\\\"carnival_android_app_key\\\" value=\\\"YOUR_APP_KEY_GOES_HERE\\\"/>\\n</platform>\",\n      \"language\": \"xml\",\n      \"name\": \"Android\"\n    }\n  ]\n}\n[/block]\nNext, set up push notifications for [iOS](doc:push-notifications-for-ios) and [Android](doc:enable-push-notifications-for-android).\n\n## Add the initialization code\nNext, you need to start the Carnival engine when your app starts. You need to do that when Cordova fires the `deviceready` event.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Starting the Carnival Engine in Cordova\",\n  \"body\": \"In Cordova, the underlying Carnival engine starts automatically, but we don't listen to in-app notifications until `startEngine` is called. On iOS, we don't register for push notifications until you either call `Carnival.startEngine(true)` or you trigger the push prompt.\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"document.addEventListener('deviceready', () => {\\n  Carnival.startEngine(true);\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nOn iOS, passing `true` to `startEngine` will also register the device for push notifications, causing iOS to show the push notification opt-in dialog. This value is ignored on Android. If you wish to register for push notifications at a later time, simply call `startEngine` with `false`, and register at a later stage using `Carnival.registerForPushNotifications`. This is useful if your app has an onboarding experience and you want to delay the push prompt until after the user lands on the pre-push stage.\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"document.addEventListener('deviceready', () => {\\n  // Start the Carnival engine, but don't register for pushes yet\\n  Carnival.startEngine(false);\\n});\\n\\n// At a later stage, trigger the push prompt\\nCarnival.registerForPushNotifications();\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]","excerpt":"Integration instructions for Cordova Apps","slug":"cordova-integration","type":"basic","title":"Cordova Integration"}

Cordova Integration

Integration instructions for Cordova Apps

Carnival supports a [Cordova](https://cordova.apache.org/) plugin that allows you to use the Carnival SDK for iOS and Android through a JavaScript interface. [block:callout] { "type": "info", "title": "Cordova minimum version", "body": "Carnival supports the following plugins:\n* `carnival-cli` version 6.5.0 or later\n* `cordova-platform-ios` version 4.1.1 or later\n* `cordova-platform-android` version 6.0.0 or later\n\nAlthough Carnival may compile on with earlier versions, it may lead to unforeseen issues." } [/block] [block:api-header] { "type": "basic", "title": "Installation" } [/block] This guide assumes Cordova is installed in your machine and your project is already initialized. ## Add the plugin Type the following command inside your project directory: [block:code] { "codes": [ { "code": "cordova plugin add https://github.com/carnivalmobile/carnival-sdk-cordova.git", "language": "shell" } ] } [/block] ## Add the SDK Key Add a preference to your `config.xml` file with your Carnival App key (from [http://app.carnivalmobile.com](http://app.carnivalmobile.com)). [block:code] { "codes": [ { "code": "<platform name=\"ios\">\n <preference name=\"carnival_ios_app_key\" value=\"YOUR_APP_KEY_GOES_HERE\" />\n</platform>", "language": "xml", "name": "iOS" }, { "code": "<platform name=\"android\">\n <preference name=\"carnival_android_app_key\" value=\"YOUR_APP_KEY_GOES_HERE\"/>\n</platform>", "language": "xml", "name": "Android" } ] } [/block] Next, set up push notifications for [iOS](doc:push-notifications-for-ios) and [Android](doc:enable-push-notifications-for-android). ## Add the initialization code Next, you need to start the Carnival engine when your app starts. You need to do that when Cordova fires the `deviceready` event. [block:callout] { "type": "info", "title": "Starting the Carnival Engine in Cordova", "body": "In Cordova, the underlying Carnival engine starts automatically, but we don't listen to in-app notifications until `startEngine` is called. On iOS, we don't register for push notifications until you either call `Carnival.startEngine(true)` or you trigger the push prompt." } [/block] [block:code] { "codes": [ { "code": "document.addEventListener('deviceready', () => {\n Carnival.startEngine(true);\n});", "language": "javascript" } ] } [/block] On iOS, passing `true` to `startEngine` will also register the device for push notifications, causing iOS to show the push notification opt-in dialog. This value is ignored on Android. If you wish to register for push notifications at a later time, simply call `startEngine` with `false`, and register at a later stage using `Carnival.registerForPushNotifications`. This is useful if your app has an onboarding experience and you want to delay the push prompt until after the user lands on the pre-push stage. [block:code] { "codes": [ { "code": "document.addEventListener('deviceready', () => {\n // Start the Carnival engine, but don't register for pushes yet\n Carnival.startEngine(false);\n});\n\n// At a later stage, trigger the push prompt\nCarnival.registerForPushNotifications();", "language": "javascript" } ] } [/block]