{"_id":"576d42354bcd290e00428950","__v":4,"parentDoc":null,"category":{"_id":"576d42354bcd290e00428943","__v":0,"project":"56a526d4e7a1622b0024fae4","version":"576d42354bcd290e00428941","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-11T15:53:26.341Z","from_sync":false,"order":1,"slug":"platforms","title":"Our SDKs"},"version":{"_id":"576d42354bcd290e00428941","project":"56a526d4e7a1622b0024fae4","__v":1,"createdAt":"2016-06-24T14:22:45.076Z","releaseDate":"2016-06-24T14:22:45.076Z","categories":["576d42354bcd290e00428942","576d42354bcd290e00428943","576d42354bcd290e00428944","576d42354bcd290e00428945","576d42354bcd290e00428946","576d42354bcd290e00428947"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2"},"project":"56a526d4e7a1622b0024fae4","user":"56703859e10ecb0d0004eebb","updates":["57e1598d9ff1e21900a72200","57e5464d7ee1b50e00b7df4a","58e79cf414f5af3900a094a6"],"next":{"pages":[],"description":""},"createdAt":"2016-02-29T14:40:21.817Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":6,"body":"The Chirp SDK for JavaScript allows you to send chirps from within your website or JavaScript project. It uses the Web Audio API to generate chirps natively within the browser, played from the visitor's speaker.\n\n__This SDK is \"send only\". It can only be used to send data via Chirp, but not receive.__\n To receive the data sent from your web project, check out the Chirp SDKs for [iOS](http://developers.chirp.io/v1/docs/chirp-for-ios) or [Android](http://developers.chirp.io/v1/docs/chirp-for-android).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Requirements\"\n}\n[/block]\nTo embed Chirp within your web project, you will need:\n* The Chirp JavaScript SDK\n* Credentials for a Chirp application, registered on the [Chirp Admin Centre](https://admin.chirp.io/)\n* A [browser that supports the Web Audio API](http://caniuse.com/#feat=audio-api)\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Registering for Credentials\"\n}\n[/block]\nTo get started, you'll need to register for a Chirp application at the [Chirp Admin Centre](https://admin.chirp.io/).\n\nUnlike our mobile SDKs, the JavaScript SDK does not need an application secret for authentication. It only uses the `application_key` for authentication, in combination with a specific `origin`.\n\nAn origin represents the host name of the website where the SDK and HTML files will be hosted.  \nYou can add a new origin by editing your application in the [Chirp Admin Centre](https://admin.chirp.io).\nPlease note that the origin should contain the hostname and port number only. \nIt should not include the protocol scheme (`http/https`)\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/3991ec2-Selection_078.png\",\n        \"Selection_078.png\",\n        1238,\n        1079,\n        \"#f2efe8\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Running the Demo\"\n}\n[/block]\nA simple demo project is included that shows the key functions of the Chirp JavaScript SDK. To use it:\n\n* In the [Chirp Admin Centre](https://admin.chirp.io), register an application, and add the origin `localhost:8000`.\n* In `demo/index.html`, replace `YOUR_APP_KEY` with the application key you obtained above.\n\nNow, serve up a webserver pointing to the `demo` directory: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"cd demo\\npython -m SimpleHTTPServer\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nFinally, go to [localhost:8000](http://localhost:8000/). Voila! You're chirping.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Installing the JavaScript SDK\"\n}\n[/block]\nWe'll now take you through installing the JavaScript SDK within your own project.\n\n### 1. Include the file `chirpSDK.min.js` within your project.\n\nCopy `chirpSDK.min.js` to your project folder, and include it within your HTML:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script src=\\\"chirpSDK.min.js\\\"></script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n\n### 2. Create a new instance of `ChirpSDK` with your application key.\n\nReplace `YOUR_APP_KEY` with your application's key.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var chirpjs = new ChirpSDK(\\\"YOUR_APP_KEY\\\");\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nAt this point, `ChirpSDK` will automatically try to authenticate your application. To catch the authentication response, you can use the `promise` property of chirpSdk instance or you can pass a callback function as a second argument.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var chirpsdk = new ChirpSDK(\\\"YOUR_APP_KEY\\\");\\nchirpsdk.promise.then(function(res) {\\n  console.info(\\\"Authentication successful!\\\");\\n}).catch(function(err) {\\n  console.error(err);\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nCatch authentication response using a callback method.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var chirpsdk = new ChirpSDK(\\\"YOUR_APP_KEY\\\", function(err, res) {\\n  if (err) {\\n      console.error(err);\\n      return;\\n  }\\n  console.info(\\\"Authentication successful!\\\");\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n###  3. Create a Chirp with data\n\nAfter the application is successfully authenticated, you can start creating new chirps. \nNOTE: You cannot create Chirps until you get authenticated.\nThe example below creates a chirp with associated JSON data, with key `foo` and value `bar`.  The response format is detailed on the Chirp API [POST /chirp documentation](http://developers.chirp.io/v2/docs/api-post-chirp)\nNOTE: The term `shortcode` has been deprecated, in favour of referring to individual chirps by their `identifier`.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var chirp = new Chirp({foo: 'bar'});\\nchirp.promise.then(function() {\\n  console.log(\\\"Chirp created!\\\");\\n}).catch(function(err) {\\n  console.error(err);\\n})\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n### 4. Create a Chirp with an identifier\nThe `chirp` contains two identifiers, the `identifier` and `identifierEncoded`. \nThe `identifierEncoded` represents the `identifier` with error-correction symbols appended, preparing it for audio playback. \n*For more information about identifiers and their encodings, see [Anatomy of a Chirp](http://developers.chirp.io/v1/docs/chirps-shortcodes).\n*\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var chirp = new Chirp(\\\"parrotbill\\\");\\nchirp.promise.then(function() {\\n  console.log(\\\"Created chirp with identifier: \\\" + chirp.identifier);\\n}).catch(function(err) {\\n  console.error(err);\\n})\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n### 5. Encode a chirp to get the `identifierEncoded`\nNOTE: this method requires internet connection\nThere will be a brief delay whilst the client contacts the server to obtain the error correction characters. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var chirp = new Chirp(\\\"parrotbill\\\");\\nchirp.promise\\n.then(chirp.encode.bind(chirp))\\n.then(function(identifierEncoded) {\\n  console.log(\\\"Created chirp with identifier: \\\" + chirp.identifier + \\\" and identifierEncoded: \\\" + chirp.identifierEncoded);\\n})\\n.catch(function(err) {\\n  console.error(err);\\n})\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n### 6. Create a chirp with `identifierEncoded`\nIf you want to create a chirp without a network connection, you can create it with the `identifierEncoded` directly.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var chirp = new Chirp(\\\"kingfishereru8acg7\\\");\\nchirp.promise.then(function() {\\n  console.log(\\\"Created chirp with identifier: \\\" + chirp.identifier + \\\" and identifierEncoded: \\\" + chirp.identifierEncoded);\\n}).catch(function(err) {\\n  console.error(err);\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n### 7. Get the Chirp associated data\nTo get the data that was attached to your chirp, you can retrieve it based on the `identifier`.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var chirp = new Chirp(\\\"parrotbill\\\");\\nchirp.promise\\n.then(chirp.getJsonData.bind(chirp))\\n.then(function(data) {\\n  console.log(data);\\n})\\n.catch(function(err) {\\n  console.error(err);\\n})\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n### 8. Play a Chirp\nYou can also encode your own `identifier`, \nwhich should be 10 characters in length (see [Anatomy of a Chirp](http://developers.chirp.io/v1/docs/chirps-shortcodes)).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"chirpSdk.chirp(new Chirp(\\\"parrotbill\\\"))\\n.then(function(){\\n  console.log(\\\"Chirp played!\\\")\\n}).catch(function(err) {\\n  console.error(err);\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"For more information about identifiers and their encodings, see [Anatomy of a Chirp](http://developers.chirp.io/v1/docs/chirps-shortcodes).\"\n}\n[/block]\n### 9. Set Protocol\nThe Chirp JavaScript SDK is capable of sending chirps in two different [protocols](http://developers.chirp.io/docs/chirp-protocols): **standard**, audible 50-bit chirps, and **ultrasonic**, inaudible 32-bit chirps. To toggle between the two:\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"chirpSdk.setProtocolNamed(\\\"ultrasonic\\\"); // to switch to the ultrasonic protocol\\nchirSdk.setProtocolNamed(\\\"standard\\\"); // to switch to the standard protocol (default)\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"For more information about Chirp Protocols see [Chirp protocols](http://developers.chirp.io/docs/chirp-protocols).\"\n}\n[/block]\n\n8. Play an Ultrasonic Chir\n\nThe ultrasonic protocol has a different carrying capacity to standard `chirps`, and so uses identifiers of a slightly different format. Ultrasonic identifiers are 8 characters long, from the hex alphabet `0-9a-f`.\n\nSimilar to \"standard\" `chirps`, if you have an internet connection, you can simply create a chirp with:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var chirp = new Chirp(\\\"3210567f\\\");\\nchirpSdk.setProtocolNamed(\\\"ultrasonic\\\");\\nchirpSdk.chirp(chirp);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n## Further Information\nFor more Chirp developer resources, visit the [Chirp Developer Hub](http://developers.chirp.io).","excerpt":"","slug":"chirp-for-javascript","type":"basic","title":"Chirp for JavaScript"}

Chirp for JavaScript


The Chirp SDK for JavaScript allows you to send chirps from within your website or JavaScript project. It uses the Web Audio API to generate chirps natively within the browser, played from the visitor's speaker. __This SDK is "send only". It can only be used to send data via Chirp, but not receive.__ To receive the data sent from your web project, check out the Chirp SDKs for [iOS](http://developers.chirp.io/v1/docs/chirp-for-ios) or [Android](http://developers.chirp.io/v1/docs/chirp-for-android). [block:api-header] { "type": "basic", "title": "Requirements" } [/block] To embed Chirp within your web project, you will need: * The Chirp JavaScript SDK * Credentials for a Chirp application, registered on the [Chirp Admin Centre](https://admin.chirp.io/) * A [browser that supports the Web Audio API](http://caniuse.com/#feat=audio-api) [block:api-header] { "type": "basic", "title": "Registering for Credentials" } [/block] To get started, you'll need to register for a Chirp application at the [Chirp Admin Centre](https://admin.chirp.io/). Unlike our mobile SDKs, the JavaScript SDK does not need an application secret for authentication. It only uses the `application_key` for authentication, in combination with a specific `origin`. An origin represents the host name of the website where the SDK and HTML files will be hosted. You can add a new origin by editing your application in the [Chirp Admin Centre](https://admin.chirp.io). Please note that the origin should contain the hostname and port number only. It should not include the protocol scheme (`http/https`) [block:image] { "images": [ { "image": [ "https://files.readme.io/3991ec2-Selection_078.png", "Selection_078.png", 1238, 1079, "#f2efe8" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Running the Demo" } [/block] A simple demo project is included that shows the key functions of the Chirp JavaScript SDK. To use it: * In the [Chirp Admin Centre](https://admin.chirp.io), register an application, and add the origin `localhost:8000`. * In `demo/index.html`, replace `YOUR_APP_KEY` with the application key you obtained above. Now, serve up a webserver pointing to the `demo` directory: [block:code] { "codes": [ { "code": "cd demo\npython -m SimpleHTTPServer", "language": "shell" } ] } [/block] Finally, go to [localhost:8000](http://localhost:8000/). Voila! You're chirping. [block:api-header] { "type": "basic", "title": "Installing the JavaScript SDK" } [/block] We'll now take you through installing the JavaScript SDK within your own project. ### 1. Include the file `chirpSDK.min.js` within your project. Copy `chirpSDK.min.js` to your project folder, and include it within your HTML: [block:code] { "codes": [ { "code": "<script src=\"chirpSDK.min.js\"></script>", "language": "html" } ] } [/block] ### 2. Create a new instance of `ChirpSDK` with your application key. Replace `YOUR_APP_KEY` with your application's key. [block:code] { "codes": [ { "code": "var chirpjs = new ChirpSDK(\"YOUR_APP_KEY\");", "language": "javascript" } ] } [/block] At this point, `ChirpSDK` will automatically try to authenticate your application. To catch the authentication response, you can use the `promise` property of chirpSdk instance or you can pass a callback function as a second argument. [block:code] { "codes": [ { "code": "var chirpsdk = new ChirpSDK(\"YOUR_APP_KEY\");\nchirpsdk.promise.then(function(res) {\n console.info(\"Authentication successful!\");\n}).catch(function(err) {\n console.error(err);\n});", "language": "javascript" } ] } [/block] Catch authentication response using a callback method. [block:code] { "codes": [ { "code": "var chirpsdk = new ChirpSDK(\"YOUR_APP_KEY\", function(err, res) {\n if (err) {\n console.error(err);\n return;\n }\n console.info(\"Authentication successful!\");\n});", "language": "javascript" } ] } [/block] ### 3. Create a Chirp with data After the application is successfully authenticated, you can start creating new chirps. NOTE: You cannot create Chirps until you get authenticated. The example below creates a chirp with associated JSON data, with key `foo` and value `bar`. The response format is detailed on the Chirp API [POST /chirp documentation](http://developers.chirp.io/v2/docs/api-post-chirp) NOTE: The term `shortcode` has been deprecated, in favour of referring to individual chirps by their `identifier`. [block:code] { "codes": [ { "code": "var chirp = new Chirp({foo: 'bar'});\nchirp.promise.then(function() {\n console.log(\"Chirp created!\");\n}).catch(function(err) {\n console.error(err);\n})", "language": "javascript" } ] } [/block] ### 4. Create a Chirp with an identifier The `chirp` contains two identifiers, the `identifier` and `identifierEncoded`. The `identifierEncoded` represents the `identifier` with error-correction symbols appended, preparing it for audio playback. *For more information about identifiers and their encodings, see [Anatomy of a Chirp](http://developers.chirp.io/v1/docs/chirps-shortcodes). * [block:code] { "codes": [ { "code": "var chirp = new Chirp(\"parrotbill\");\nchirp.promise.then(function() {\n console.log(\"Created chirp with identifier: \" + chirp.identifier);\n}).catch(function(err) {\n console.error(err);\n})", "language": "javascript" } ] } [/block] ### 5. Encode a chirp to get the `identifierEncoded` NOTE: this method requires internet connection There will be a brief delay whilst the client contacts the server to obtain the error correction characters. [block:code] { "codes": [ { "code": "var chirp = new Chirp(\"parrotbill\");\nchirp.promise\n.then(chirp.encode.bind(chirp))\n.then(function(identifierEncoded) {\n console.log(\"Created chirp with identifier: \" + chirp.identifier + \" and identifierEncoded: \" + chirp.identifierEncoded);\n})\n.catch(function(err) {\n console.error(err);\n})", "language": "javascript" } ] } [/block] ### 6. Create a chirp with `identifierEncoded` If you want to create a chirp without a network connection, you can create it with the `identifierEncoded` directly. [block:code] { "codes": [ { "code": "var chirp = new Chirp(\"kingfishereru8acg7\");\nchirp.promise.then(function() {\n console.log(\"Created chirp with identifier: \" + chirp.identifier + \" and identifierEncoded: \" + chirp.identifierEncoded);\n}).catch(function(err) {\n console.error(err);\n});", "language": "javascript" } ] } [/block] ### 7. Get the Chirp associated data To get the data that was attached to your chirp, you can retrieve it based on the `identifier`. [block:code] { "codes": [ { "code": "var chirp = new Chirp(\"parrotbill\");\nchirp.promise\n.then(chirp.getJsonData.bind(chirp))\n.then(function(data) {\n console.log(data);\n})\n.catch(function(err) {\n console.error(err);\n})", "language": "javascript" } ] } [/block] ### 8. Play a Chirp You can also encode your own `identifier`, which should be 10 characters in length (see [Anatomy of a Chirp](http://developers.chirp.io/v1/docs/chirps-shortcodes)). [block:code] { "codes": [ { "code": "chirpSdk.chirp(new Chirp(\"parrotbill\"))\n.then(function(){\n console.log(\"Chirp played!\")\n}).catch(function(err) {\n console.error(err);\n});", "language": "javascript" } ] } [/block] [block:callout] { "type": "info", "body": "For more information about identifiers and their encodings, see [Anatomy of a Chirp](http://developers.chirp.io/v1/docs/chirps-shortcodes)." } [/block] ### 9. Set Protocol The Chirp JavaScript SDK is capable of sending chirps in two different [protocols](http://developers.chirp.io/docs/chirp-protocols): **standard**, audible 50-bit chirps, and **ultrasonic**, inaudible 32-bit chirps. To toggle between the two: [block:code] { "codes": [ { "code": "chirpSdk.setProtocolNamed(\"ultrasonic\"); // to switch to the ultrasonic protocol\nchirSdk.setProtocolNamed(\"standard\"); // to switch to the standard protocol (default)", "language": "javascript" } ] } [/block] [block:callout] { "type": "info", "body": "For more information about Chirp Protocols see [Chirp protocols](http://developers.chirp.io/docs/chirp-protocols)." } [/block] 8. Play an Ultrasonic Chir The ultrasonic protocol has a different carrying capacity to standard `chirps`, and so uses identifiers of a slightly different format. Ultrasonic identifiers are 8 characters long, from the hex alphabet `0-9a-f`. Similar to "standard" `chirps`, if you have an internet connection, you can simply create a chirp with: [block:code] { "codes": [ { "code": "var chirp = new Chirp(\"3210567f\");\nchirpSdk.setProtocolNamed(\"ultrasonic\");\nchirpSdk.chirp(chirp);", "language": "javascript" } ] } [/block] ## Further Information For more Chirp developer resources, visit the [Chirp Developer Hub](http://developers.chirp.io).