{"_id":"576d42354bcd290e0042894c","__v":9,"parentDoc":null,"project":"56a526d4e7a1622b0024fae4","user":"56bc6af27c91881900089bac","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"},"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"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-11T15:54:32.113Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"The Chirp iOS SDK is designed to get your iPhone and iPad applications chirping quickly and easily. Our SDK primarily uses a block-based approach to handle asynchronous operations like chirping and network calls, and also provides an extensive set of `NSNotifications` to provide you with updates on events and state within the SDK. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Swift\",\n  \"body\": \"The Chirp SDK is fully compatible with Swift. To use it, make sure you have included it in your [bridging header](https://developer.apple.com/library/ios/documentation/Swift/Conceptual/BuildingCocoaApps/MixandMatch.html).\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Basic setup\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"If you do not yet have an app key and secret, please [register and create a new application](https://admin.chirp.io/sign_up/create_profile).\",\n  \"title\": \"App Credentials\"\n}\n[/block]\n\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"NSMicrophoneUsageDescription\",\n  \"body\": \"Apple requires your application's plist to contain a description for why you require access to the device's microphone. Make sure you add this before running your app.\\n\\nhttps://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html\"\n}\n[/block]\nThe app key and app secret identify your Chirp-enabled app, and allows your account to track per-chirp usage and behaviour across your install base. \n\nYou may check for successful completion by using the `setAppKey:andSecret:withCompletion:` method, which informs your code that authentication has completed successfully.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[[ChirpSDK sdk] setAppKey:YOUR_APP_KEY\\n               andSecret:YOUR_APP_SECRET\\n          withCompletion:^(BOOL authenticated, NSError *error)\\n{\\n   if (authenticated) { NSLog(:::at:::\\\"Authenticated OK.\\\"); }\\n}];\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"\",\n  \"body\": \"Note that when the device is not connected to the internet, authentication cannot take place and so the completion block is not called. The app will proceed with a default set of credentials. For this reason, make sure you don't put any mission-critical code inside the `withCompletion` handler.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Basic operation\"\n}\n[/block]\n## Send a chirp\n\nChirp offline when you need to send small amounts of information. Offline chirps only send the identifier (e.g. \"7hj2a21aac\") between devices. This allows devices  to send and receive data even when in airplane-mode.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Chirp *chirp = [[Chirp alloc] initWithIdentifier:@\\\"a7cnn9c0li\\\"];\\n[chirp chirpWithCompletion:^(Chirp *chirp, NSError *error)\\n {\\n     NSLog(@\\\"Completion: %@\\\", chirp.identifier);\\n     if (error)\\n     {\\n         NSLog(@\\\"ERROR: %@\\\", error);\\n     }\\n }];\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\nBy default, `offlineMode` is disabled, meaning that the SDK will query the API for data when any identifier is heard. To start listening for chirps in offline mode:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[[ChirpSDK sdk] setChirpHeardBlock:^(Chirp *chirp NSError *error)\\n{\\n  if (error)\\n  {\\n    NSLog(@\\\"An error occurred: %@\\\", error);\\n  }\\n  else\\n  {\\n\\t  NSDictionary *data = chirp.data;\\n\\t  NSLog(@\\\"Got chirp with identifier %@, data %@\\\", chirp.identifier, chirp.data);\\n  }\\n}];\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\nTo send a chirp:\n\n## Online mode\n\nChirp's \"online\" mode is used to send larger amounts of complex data, such as dictionaries. Anything that can be encoded as a JSON object can be chirped: numbers, strings, arrays, and dictionaries.\n\nTo start listening online for chirps:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[[ChirpSDK sdk] setChirpHeardBlock:^(Chirp *chirp, NSError *error)\\n{\\n  NSLog(@\\\"Heard a chirp: %@\\\", chirp.identifier);\\n  [chirp fetchAssociatedDataWithCompletion:^(Chirp *chirp, NSError *error) {\\n  \\t  NSLog(@\\\"Got its associateddata: %@\\\", chirp.data);\\n  }];\\n}];\",\n      \"language\": \"objectivec\",\n      \"gist\": \"54f89cf71492e2956add\"\n    }\n  ]\n}\n[/block]\nTo send a chirp, we create an Chirp instance with its associated data:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[Chirp createChirpWithAssociatedData:@{ @\\\"key\\\" : @\\\"value\\\" }\\n                           withCompletion:^(Chirp *chirp, NSError *error)\\n{\\n    if (chirp)\\n    {\\n       NSLog(@\\\"Created a chirp with identifier: %@\\\", chirp.identifier);\\n       [chirp chirp];\\n    }\\n}];\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\nThis encapsulates the specified `NSDictionary` and adds it on the network, returning a chirp object which can then be played from the loudspeaker using the `[chirp chirp]` method. \n \nKeys must be instances of `NSString`. Values can be instances of `NSString`, `NSNumber`, `NSArray`, `NSDictionary`.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Data size\",\n  \"body\": \"Our standard product limits the attached data dictionary's size to 4096 bytes\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Advanced\"\n}\n[/block]\nFor a full list of every method our SDK offers please refer to the `ChirpSDK/ChirpSDK.h` header in the distributed framework.\n\nHere are a list of some of the less common behaviours which can be accessed through our SDK.\n\n## version\n\nThis is useful for debugging and reporting - please include version information with any [bug reports](doc:bug-reporter).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[[ChirpSDK sdk] version]; // 2.1.3 (engine 2.0.0)\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\n## Chirp volume\n\nSet and get Chirp's output volume, independent from the device hardware. This adjusts the volume of the chirp output between zero and 1.0f. \n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Attempting to chirp whilst the volume is set to 0.0 will result in an error inside the chirp method's completion block.\",\n  \"title\": \"Chirping volume\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[[ChirpSDK sdk] setVolume:0.6];\\n\\n[ChirpSDK sdk].volume; // 0.6\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\n## System audio volume\n\nThis read-only property is a convenience method for obtaining the current hardware volume of the device.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[[ChirpSDK sdk] systemAudioVolume]; // 0.9\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\n## Random Identifier\n\nConvenience method for generating a valid random chirp identifier.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[[ChirpSDK sdk] randomIdentifier]; // 8nk34aa0e0\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\n## isValid Identifier\n\nConvenience method for testing whether a string is in the valid identifier format and able to be chirped.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[[ChirpSDK sdk] isValidIdentifier:@\\\"8nk34aa0e0\\\"]; YES\\n\\n[[ChirpSDK sdk] isValidIdentifier:@\\\"NotValidXXXXXXX!\\\"]; NO\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]","excerpt":"Using the Chirp SDKs for iPhone and iPad","slug":"chirp-for-ios","type":"basic","title":"Chirp for iOS"}

Chirp for iOS

Using the Chirp SDKs for iPhone and iPad

The Chirp iOS SDK is designed to get your iPhone and iPad applications chirping quickly and easily. Our SDK primarily uses a block-based approach to handle asynchronous operations like chirping and network calls, and also provides an extensive set of `NSNotifications` to provide you with updates on events and state within the SDK. [block:callout] { "type": "info", "title": "Swift", "body": "The Chirp SDK is fully compatible with Swift. To use it, make sure you have included it in your [bridging header](https://developer.apple.com/library/ios/documentation/Swift/Conceptual/BuildingCocoaApps/MixandMatch.html)." } [/block] [block:api-header] { "type": "basic", "title": "Basic setup" } [/block] [block:callout] { "type": "info", "body": "If you do not yet have an app key and secret, please [register and create a new application](https://admin.chirp.io/sign_up/create_profile).", "title": "App Credentials" } [/block] [block:callout] { "type": "danger", "title": "NSMicrophoneUsageDescription", "body": "Apple requires your application's plist to contain a description for why you require access to the device's microphone. Make sure you add this before running your app.\n\nhttps://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html" } [/block] The app key and app secret identify your Chirp-enabled app, and allows your account to track per-chirp usage and behaviour across your install base. You may check for successful completion by using the `setAppKey:andSecret:withCompletion:` method, which informs your code that authentication has completed successfully. [block:code] { "codes": [ { "code": "[[ChirpSDK sdk] setAppKey:YOUR_APP_KEY\n andSecret:YOUR_APP_SECRET\n withCompletion:^(BOOL authenticated, NSError *error)\n{\n if (authenticated) { NSLog(@\"Authenticated OK.\"); }\n}];", "language": "objectivec" } ] } [/block] [block:callout] { "type": "info", "title": "", "body": "Note that when the device is not connected to the internet, authentication cannot take place and so the completion block is not called. The app will proceed with a default set of credentials. For this reason, make sure you don't put any mission-critical code inside the `withCompletion` handler." } [/block] [block:api-header] { "type": "basic", "title": "Basic operation" } [/block] ## Send a chirp Chirp offline when you need to send small amounts of information. Offline chirps only send the identifier (e.g. "7hj2a21aac") between devices. This allows devices to send and receive data even when in airplane-mode. [block:code] { "codes": [ { "code": "Chirp *chirp = [[Chirp alloc] initWithIdentifier:@\"a7cnn9c0li\"];\n[chirp chirpWithCompletion:^(Chirp *chirp, NSError *error)\n {\n NSLog(@\"Completion: %@\", chirp.identifier);\n if (error)\n {\n NSLog(@\"ERROR: %@\", error);\n }\n }];", "language": "objectivec" } ] } [/block] By default, `offlineMode` is disabled, meaning that the SDK will query the API for data when any identifier is heard. To start listening for chirps in offline mode: [block:code] { "codes": [ { "code": "[[ChirpSDK sdk] setChirpHeardBlock:^(Chirp *chirp NSError *error)\n{\n if (error)\n {\n NSLog(@\"An error occurred: %@\", error);\n }\n else\n {\n\t NSDictionary *data = chirp.data;\n\t NSLog(@\"Got chirp with identifier %@, data %@\", chirp.identifier, chirp.data);\n }\n}];", "language": "objectivec" } ] } [/block] To send a chirp: ## Online mode Chirp's "online" mode is used to send larger amounts of complex data, such as dictionaries. Anything that can be encoded as a JSON object can be chirped: numbers, strings, arrays, and dictionaries. To start listening online for chirps: [block:code] { "codes": [ { "code": "[[ChirpSDK sdk] setChirpHeardBlock:^(Chirp *chirp, NSError *error)\n{\n NSLog(@\"Heard a chirp: %@\", chirp.identifier);\n [chirp fetchAssociatedDataWithCompletion:^(Chirp *chirp, NSError *error) {\n \t NSLog(@\"Got its associateddata: %@\", chirp.data);\n }];\n}];", "language": "objectivec", "gist": "54f89cf71492e2956add" } ] } [/block] To send a chirp, we create an Chirp instance with its associated data: [block:code] { "codes": [ { "code": "[Chirp createChirpWithAssociatedData:@{ @\"key\" : @\"value\" }\n withCompletion:^(Chirp *chirp, NSError *error)\n{\n if (chirp)\n {\n NSLog(@\"Created a chirp with identifier: %@\", chirp.identifier);\n [chirp chirp];\n }\n}];", "language": "objectivec" } ] } [/block] This encapsulates the specified `NSDictionary` and adds it on the network, returning a chirp object which can then be played from the loudspeaker using the `[chirp chirp]` method. Keys must be instances of `NSString`. Values can be instances of `NSString`, `NSNumber`, `NSArray`, `NSDictionary`. [block:callout] { "type": "warning", "title": "Data size", "body": "Our standard product limits the attached data dictionary's size to 4096 bytes" } [/block] [block:api-header] { "type": "basic", "title": "Advanced" } [/block] For a full list of every method our SDK offers please refer to the `ChirpSDK/ChirpSDK.h` header in the distributed framework. Here are a list of some of the less common behaviours which can be accessed through our SDK. ## version This is useful for debugging and reporting - please include version information with any [bug reports](doc:bug-reporter). [block:code] { "codes": [ { "code": "[[ChirpSDK sdk] version]; // 2.1.3 (engine 2.0.0)", "language": "objectivec" } ] } [/block] ## Chirp volume Set and get Chirp's output volume, independent from the device hardware. This adjusts the volume of the chirp output between zero and 1.0f. [block:callout] { "type": "warning", "body": "Attempting to chirp whilst the volume is set to 0.0 will result in an error inside the chirp method's completion block.", "title": "Chirping volume" } [/block] [block:code] { "codes": [ { "code": "[[ChirpSDK sdk] setVolume:0.6];\n\n[ChirpSDK sdk].volume; // 0.6", "language": "objectivec" } ] } [/block] ## System audio volume This read-only property is a convenience method for obtaining the current hardware volume of the device. [block:code] { "codes": [ { "code": "[[ChirpSDK sdk] systemAudioVolume]; // 0.9", "language": "objectivec" } ] } [/block] ## Random Identifier Convenience method for generating a valid random chirp identifier. [block:code] { "codes": [ { "code": "[[ChirpSDK sdk] randomIdentifier]; // 8nk34aa0e0", "language": "objectivec" } ] } [/block] ## isValid Identifier Convenience method for testing whether a string is in the valid identifier format and able to be chirped. [block:code] { "codes": [ { "code": "[[ChirpSDK sdk] isValidIdentifier:@\"8nk34aa0e0\"]; YES\n\n[[ChirpSDK sdk] isValidIdentifier:@\"NotValidXXXXXXX!\"]; NO", "language": "objectivec" } ] } [/block]