{"_id":"56c418efc4796b0d007ef03a","version":{"_id":"56bc8e689afb8b0d00d62dd2","project":"56bc8e679afb8b0d00d62dcf","__v":18,"createdAt":"2016-02-11T13:36:40.146Z","releaseDate":"2016-02-11T13:36:40.146Z","categories":["56bc8e689afb8b0d00d62dd3","56c3c837bc41330d009f25ed","56c3c83e521f350d00d348eb","56c3c8452d97560d00e23cd8","56c3c85234df460d00c2beb8","56c4180d70187b17005f43b4","56c418162d97560d00e23cf6","56c4181cc4796b0d007ef039","56c4182370187b17005f43b5","56c418292e75e01700986052","56c4183328bd680d005e7ac6","56c4183bbb64720d00552b88","56c418414040602b0064cea0","56c4184754b6030d00ec29a1","56c4184c28bd680d005e7ac7","56c4185370187b17005f43b6","56c4185b6063071700500cfc","582a98b6f8c0a0190053d7a5"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"__v":3,"category":{"_id":"56c4180d70187b17005f43b4","__v":5,"project":"56bc8e679afb8b0d00d62dcf","version":"56bc8e689afb8b0d00d62dd2","pages":["56c418c854b6030d00ec29a2","56c418e670187b17005f43b7","56c418efc4796b0d007ef03a","56c418f94040602b0064cea1","56ca81146b58fb0b00c6d2fc"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-17T06:49:49.187Z","from_sync":false,"order":1,"slug":"buddy-basics","title":"Buddy Basics"},"parentDoc":null,"project":"56bc8e679afb8b0d00d62dcf","githubsync":"","user":"56b98db7bb36440d0001f492","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-17T06:53:35.002Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"Buddy offers a flexible and powerful metadata system on all objects.  This system makes it easy to store any extra information that your application needs.\n\n### Metadata Basics\n\nMetadata on Buddy can be thought of as a key-value property bag available on any Buddy object.  In other words, given a Buddy object, you can add arbitrary values to that object, and then retrieve them later.  \n\nFor example, imagine you've added a photo to Buddy using the Pictures functionality.  Natively, a picture has some properties on it like `caption`, in addition to the standard properties on all Buddy objects like owner, creation and modified time, and location.  But you'd like to store some categorization information about the photo.  \n\nThis is easy with metadata.  You simply [set a metadata key](doc:set-metadata-value) to the photo named \"category\", with a value of your choosing, specifying ID of your photo object.  Later you can [retrieve that value](doc:get-metadata) for display in your application.\n\nEach SDK has its own support for this, but if you were using the [JavaScript SDK](doc:javascript-sdk), you would do this as follows:\n\n    var photoId;\n    Buddy.put('/metadata/' + photoId, \n    {\n        values: {\n            category: \"some category\"\n        }\n      }\n     );\n\nThen later you could retrieve this value via `Buddy.get('/metadata/' + photoId + '/category')`.\n\nOr, you can push a single key:\n\n    var photoId;\n    Buddy.put(\n      '/metadata/' + photoId + '/likes', \n      {\n        value: 27,\n        visibility: 'App'\n      }\n    );\n\nOr, for numeric values, you can use the **increment** function to update the value by one (or some other value):\n\n`Buddy.put('/metadata/' + photoId '/likes/increment', {visibility: 'App'})`\n\n#### Key Visibility\n\nMetadata values have two available visibility scopes: `App` and `User`.  These control who is able to view and modify the values:\n\n* **User**: (Default when caller sends user access token)  Each user can have their own value, only visible to the user that set it.\n* **App**: (Default when caller sends device access token) The key is visible (and editable) by any application user\n\nConsidering our photo scenario above, you could use scoped metadata to implement a \"favorites\" and \"likes\" in your application:\n\n* Making a photo a favorite is something each user may do, and is value that is per-user.  To implement this, simply set a metadata value `favorite = true` on the photo.  Since `User` visibility is the default, you don't need to pass the parameter.\n\n* Counting \"likes\" on a photo is an app-wide operation.  Use the metadata \"increment\" operation with a key called \"likes\" to add a like to a photo, and set it's visibility to `App`.  Any user can then modify this value.\n\n#### Key Encoding\n\nIf your key contains URL-reserved characters, which are any of the following:\n! * ' ( ) ; : :::at::: & = + $ , / ? # [ ]\n\nYou must percent-encode them before using them within a key. This is also known as URL-encoding.\n\nFor example, if your desired key is:  First+Second!\n\nIt should be percent-encoded as:  First%2bSecond%21\n\nThen it can be passed to the Buddy.put method as '/metadata/First%2bSecond%21':\n\n    var photoId;\n    Buddy.put(\n      '/metadata/' + photoId + '/First%2bSecond%21', \n      {\n        value: 27\n      }\n    );\n\nMost programming languages contain support for percent-encoding. For more details see [percent-encoding](http://en.wikipedia.org/wiki/Percent-encoding).\n\n### Application Metadata\n\nYou can also add metadata to the application itself.  You can either pass the application's ID (the value you get from the Developer Dashboard), or you can pass `app` as a shorthand for this.","excerpt":"","slug":"metadata","type":"basic","title":"Metadata"}
Buddy offers a flexible and powerful metadata system on all objects. This system makes it easy to store any extra information that your application needs. ### Metadata Basics Metadata on Buddy can be thought of as a key-value property bag available on any Buddy object. In other words, given a Buddy object, you can add arbitrary values to that object, and then retrieve them later. For example, imagine you've added a photo to Buddy using the Pictures functionality. Natively, a picture has some properties on it like `caption`, in addition to the standard properties on all Buddy objects like owner, creation and modified time, and location. But you'd like to store some categorization information about the photo. This is easy with metadata. You simply [set a metadata key](doc:set-metadata-value) to the photo named "category", with a value of your choosing, specifying ID of your photo object. Later you can [retrieve that value](doc:get-metadata) for display in your application. Each SDK has its own support for this, but if you were using the [JavaScript SDK](doc:javascript-sdk), you would do this as follows: var photoId; Buddy.put('/metadata/' + photoId, { values: { category: "some category" } } ); Then later you could retrieve this value via `Buddy.get('/metadata/' + photoId + '/category')`. Or, you can push a single key: var photoId; Buddy.put( '/metadata/' + photoId + '/likes', { value: 27, visibility: 'App' } ); Or, for numeric values, you can use the **increment** function to update the value by one (or some other value): `Buddy.put('/metadata/' + photoId '/likes/increment', {visibility: 'App'})` #### Key Visibility Metadata values have two available visibility scopes: `App` and `User`. These control who is able to view and modify the values: * **User**: (Default when caller sends user access token) Each user can have their own value, only visible to the user that set it. * **App**: (Default when caller sends device access token) The key is visible (and editable) by any application user Considering our photo scenario above, you could use scoped metadata to implement a "favorites" and "likes" in your application: * Making a photo a favorite is something each user may do, and is value that is per-user. To implement this, simply set a metadata value `favorite = true` on the photo. Since `User` visibility is the default, you don't need to pass the parameter. * Counting "likes" on a photo is an app-wide operation. Use the metadata "increment" operation with a key called "likes" to add a like to a photo, and set it's visibility to `App`. Any user can then modify this value. #### Key Encoding If your key contains URL-reserved characters, which are any of the following: ! * ' ( ) ; : @ & = + $ , / ? # [ ] You must percent-encode them before using them within a key. This is also known as URL-encoding. For example, if your desired key is: First+Second! It should be percent-encoded as: First%2bSecond%21 Then it can be passed to the Buddy.put method as '/metadata/First%2bSecond%21': var photoId; Buddy.put( '/metadata/' + photoId + '/First%2bSecond%21', { value: 27 } ); Most programming languages contain support for percent-encoding. For more details see [percent-encoding](http://en.wikipedia.org/wiki/Percent-encoding). ### Application Metadata You can also add metadata to the application itself. You can either pass the application's ID (the value you get from the Developer Dashboard), or you can pass `app` as a shorthand for this.