# MBurger Documentation🍔 ## Welcome to the MBurger official documentation {% hint style="success" %} Here you will learn everything you need to know about MBurger and how to use it at its best! {% endhint %} {% content-ref url="/pages/-MDJIriJErZoldTGE43r" %} [Broken mention](broken://pages/-MDJIriJErZoldTGE43r) {% endcontent-ref %} {% content-ref url="/pages/-MDysp8IXk8dxa7Bi592" %} [ API](/api-docs-1) {% endcontent-ref %} {% content-ref url="/pages/-MDyun9cQnVCYlMec-Kz" %} [ Android SDK](/android-docs) {% endcontent-ref %} {% content-ref url="/pages/-MDyushOSxzgpCkxNoVP" %} [ iOS SDK](/ios-docs) {% endcontent-ref %} {% content-ref url="/pages/-MDyusS5Zdrsv4woSSCk" %} [ PHP SDK](/php-docs) {% endcontent-ref %} {% content-ref url="/pages/-MDyvoZsuUg4QV7L7Hz1" %} [ JavaScript SDK](/javascript-docs-1) {% endcontent-ref %} {% content-ref url="/pages/-MIOIHPwkxvD8RCuhzKM" %} [Flutter SDK](/flutter-sdk) {% endcontent-ref %} {% content-ref url="/pages/-MDyus8OPRRFvKUtonEn" %} [ Sample App](/sample-app-1) {% endcontent-ref %} # API # Introduction {% hint style="info" %} This document will help you through **MBurger API** integration. {% endhint %} You will learn how to handle authentication, interact with data, and take advantage of the awesome features offered by MBurger. {% content-ref url="/pages/-MDJS4mGanI64gn-9MKk" %} [Getting Started](/api-docs-1/introduction/getting-started) {% endcontent-ref %} {% content-ref url="/pages/-MDJS2aMSXM9yViQ3FF6" %} [Structure](/api-docs-1/introduction/structure) {% endcontent-ref %} # Getting Started Before starting, make sure to have access to an existent project (with an admin or developer role) or create a new [MBurger project](https://mburger.cloud/register). After that, navigate to Settings > **API Keys** to create an auth token, which you will need to interact with the APIs. {% hint style="info" %} Be aware that for most use cases you should obtain an API key with **read** permission. If you will use creation or editing API you'll need to add **write** and **delete** permissions. {% endhint %} The MBurger API is organized around REST, resource-oriented URLs and JSON responses. It aims to facilitate the life of the developer offering a robust query and filtering system through URLs. Use HTTPS when calling all methods. All media files are served by the CloudFront CDN through `https://cdn.mburger.cloud`. {% hint style="info" %} Is highly suggested to familiarize yourself with the structure of an MBurger project and to **read** the [Common](https://docs.mburger.cloud/api-docs/common) section before start exploring the APIs documentation. {% endhint %} # Structure Every Mburger project data model is composed of 3 main entities: * **Blocks**: a block is composed of *elements* and defines the feature data model within the project. Each block represents a specific feature defining its structure. * **Elements**: they are the basic elements with which to build the data model, forming a *block* structure. An element can be a text field, an image field, an address field and many others. * **Sections**: represents the data itself. A *section* belongs to a *block* inheriting its structure. A *block* can contain one or more *sections*. ### A Simple Sample A simple example can be building a News feature. First create a new *block* called News and define its structure using 3 *elements*: * a *text element*: the title of the news * an *image element*: an image associated with to the news * a *datetime element*: the date of the news Defined the News *block* structure, we can add one or more *sections*. Each section is a news with a title, image and a datetime. {% hint style="info" %} A block and its structure can only be created from the web dashboard (only **admin** and **developers** roles). Once a block is created, you can use APIs to create/update/delete sections. {% endhint %} # Common Path {% hint style="info" %} In this section you’ll find useful information on how to use MBurger API. {% endhint %} {% content-ref url="/pages/-MDJTWBQ2-xbCu6JkKPQ" %} [Basics](/api-docs-1/common/basics) {% endcontent-ref %} {% content-ref url="/pages/-MDJTVlthg8qchNACCMn" %} [POST Bodies](/api-docs-1/common/post-bodies) {% endcontent-ref %} {% content-ref url="/pages/-MDJTVORVBfHnDblx8FS" %} [POST Relations](/api-docs-1/common/relations) {% endcontent-ref %} {% content-ref url="/pages/-MDJTUugkBItcKEnhDU6" %} [Evaluating Responses](/api-docs-1/common/evaluating-responses) {% endcontent-ref %} # Basics When interacting with MBurger API pass arguments as: * `GET` querystring parameters * `POST` parameters presented as `application/x-www-form-urlencoded` or a mix of both `GET` and `POST` parameters * Some write APIs allow arguments `application/json` attributes. * File uploads expects `multipart/form-data`, which is a fancy way of asking you to send most parameters as `application/x-www-form-urlencoded` key/value pairs, but send files in their native content type. ## Query Builder Some `GET` request like for *blocks* and *sections* adopts a powerful query builder system. Using 3 parameters `include`, `filter` and `sort` in the request query string the client can build requests that reflects perfectly their needs. {% hint style="info" %} Check in which APIs this system is available to see all the available parameters. {% endhint %} ## Headers MBurger uses some HTTP headers to handle requests. In particular, they are used to authenticate and to know which kind of data one should expect from the client and vice versa. All used headers are shown in the table below, but they can change based on which API you are calling. | Header | Always Required | Description | | ----------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Accept | Yes | Define the data type that client is expecting in response. For API, it should always be `application/json`. | | X-MBurger-Token | Yes | Contains the token to authenticate every API call. | | X-MBurger-Version | Yes | Define the API version you want to use. The minimum and actual is 3. | | Authorization | No | Allows MBurger to authenticate mobile users. Required only for APIs regarding mobile users. | | Content-Type | No | Define the data type that MBurger is expecting in request data. Required when data in POSTed to MBurger, normally it is `application/x-www-form-urlencoded`. | # POST Bodies {% hint style="info" %} When sending a HTTP `POST`, you may present your arguments as either standard POST parameters or use `multipart/form-data` if file are included. {% endhint %} ## URL Encoded When sending URL- encoded data, set your HTTP `Content-Type` header to `application/x-www-form-urlencoded` and present your key/value pairs according to [RFC-3986](https://tools.ietf.org/html/rfc3986). For example, a`POST`request to create a section might look something like this: ```http POST /api/blocks//sections HTTP/1.1 Accept: application/json X-MBurger-Token: X-MBurger-Version: Content-Type: application/x-www-form-urlencoded; charset=utf-8 elements[en][title]=Awesome+Title&elements[en][content]=Awesome+Content&elements[en][title]=Titolo&elements[en][content]=Contenuto ``` In this example, you are creating one section with two elements `title` and `content` both in English and Italian. {% hint style="warning" %} As you can see, every key of an element **must** be in the form of `elements[LOCALE][ELEMENT_NAME]` {% endhint %} ## Multipart Encoded If you have to send files you must use `multipart/form-data`. An example: ```http POST /api/blocks//sections HTTP/1.1 Accept: application/json X-MBurger-Token: X-MBurger-Version: Content-Type: multipart/form-data; charset=utf-8; boundary=YOUR_BOUNDARY --YOUR_BOUNDARY Content-Disposition: form-data; name="elements[en][title]" Title --YOUR_BOUNDARY Content-Disposition: form-data; name="elements[en][image][0]"; filename="image1.jpg" Content-Type: image/jpeg --YOUR_BOUNDARY Content-Disposition: form-data; name="elements[en][image][1]"; filename="image2.jpg" Content-Type: image/jpeg --YOUR_BOUNDARY-- ``` In this example, you are creating one section with two elements `title` and `image` only in English. {% hint style="warning" %} As you can see, every key of a media element (*image*, *audio*, *video*, *document*, *file*) **must** be in the form of `elements[LOCALE][ELEMENT_NAME][INDEX]`. {% endhint %} {% hint style="info" %} Instead ***relation*** elements doesn't require a locale so the key **must** be in the form of `ELEMENT_NAME[INDEX]` You can see an example in the [Relations](https://docs.mburger.cloud/api-docs/common/relations) section :wink: {% endhint %} ## # POST Relations {% hint style="info" %} The ***relation*** element is used to create a relation between two sections of your MBurger project. For example, you can use it to link an article to an author, a picture to a point of interest, a video to an event, etc {% endhint %} In this example we want to create a section with only one element of type *relation* called `author-relation`. The relation field is populated with 2 sections ID: `SECTION1_ID` and `SECTION2_ID`. ```http POST /api/blocks//sections HTTP/1.1 Accept: application/json X-MBurger-Token: X-MBurger-Version: Content-Type: application/x-www-form-urlencoded; charset=utf-8 author-relation[0]=&author-relation[1]= ``` > curl ```bash curl -X "POST" "/api/blocks//sections" \ -H 'Accept: application/json' \ -H 'X-MBurger-Token: ' \ -H 'X-MBurger-Version: ' \ -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \ --data-urlencode "relation[0]=&relation[1]=" ``` # Evaluating Responses All API responses contain a JSON object, which will always contain a top-level integer property `status_code`, indicating success (`= 0`) or failure (`!= 0`). {% hint style="info" %} In case of errors, are adopted HTTP status codes are adopted and a JSON string property `message` that explain the error. {% endhint %} ## Errors MBurger APIs uses the following HTTP error codes: | Code | Meaning | Description | | ---- | --------------------- | ------------------------------------------------------------------ | | 400 | Bad Request | Your request is invalid. | | 401 | Unauthorized | Your API key is wrong or not present. | | 403 | Forbidden | You don't have permission to access this resource. | | 404 | Not Found | The requested resource can not be found. | | 405 | Method Not Allowed | You tried to use an invalid method. | | 406 | Not Acceptable | You requested a format that isn't json. | | 422 | Unprocessable Entity | Your request did not pass the input validation. | | 429 | Too Many Requests | You're requesting too many! Slow down! | | 500 | Internal Server Error | We had a problem with our server. Try again later. | | 503 | Service Unavailable | We're temporarily offline for maintenance. Please try again later. | ## Examples On authentication error is returned an HTTP 401 and a JSON like this: ```bash { "message": "The project token is not present." } ``` On bad request error is returned an HTTP 400 and a JSON like this: ```bash { "message": "Given filter(s) `available` are not allowed. Allowed filter(s) are `id, subscription, value, geofence`." } ``` On permission error is returned an HTTP 403 and a JSON like this: ```bash { "message": "This action is unauthorized." } ``` On not found error is returned an HTTP 404 and a JSON like this: ```bash { "message": "The requested resource can not be found." } ``` On validation error is returned an HTTP 422 and a JSON like this: ```bash { "message": "The given data was invalid.", "errors": { "email": [ "The email has already been taken." ] } } ``` # API Authentication The MBurger APIs offers 2 authentication providers: * **project**: identifies a single project. This authentication is always requested while using API. It's based on a token header to add in every request. To authenticate with the *project* provider the request **must include** the following headers: | Header | Description | | ----------------- | ------------------------------------------------ | | X-MBurger-Token | Your generated API key from the dashboard | | X-MBurger-Version | MBurger API version, actual version is now **3** | | Accept | application/json | * **mobile**: identifies a single user in a project. It's available only when the *users* feature is enabled and is based on JWT token header to add in every request. To authenticate with the *mobile* provider the request **must include** the following headers: | Header | Description | | ------------- | ---------------- | | Authorization | Bearer *JWT* | | Accept | application/json | The JWT token is obtained through the authentication API. {% hint style="info" %} If you are using Android or iOS, you will find open source SDKs in order to make mobile development easier. You can find more information for [iOS](https://github.com/Mumble-SRL/MBurger-iOS) and [Android](https://github.com/Mumble-SRL/MBurger-Android). {% endhint %} # Project ## Get Project {% hint style="info" %} How to obtain all project data. {% endhint %} {% tabs %} {% tab title="Request" %} `GET https://mburger.cloud/api/project` ```bash curl https://mburger.cloud/api/project?locale=it&include=sections&sort=-title -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" ``` #### Parameters | Name | Type | Required | Description | | ------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- | | include | string | No | Specify which relations to load and include in response. | | image\_format | string | No | Specify which image dimension to include in response. Values are *thumb*, *medium*, *large* and *original*. Default is *medium*. | #### Includes | Name | Description | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | blocks | This relation will return all blocks of the project. You can also send *blocks.sections*, *blocks.structure* or *blocks.sections.elements* to obtain all the data in a single API call. | | beacons | This relation will load all beacons associated with the project | | contracts | This relation will return all contracts uploaded to the project | | {% endtab %} | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0, "body": { "id": 1, "name": "Awesome Project", "has_analytics": false, "has_beacons": true, "has_users": true, "has_multilanguage": true, "has_live_messages": true, "has_push": true, "has_subscriptions": false, "has_payments": true, "tz": "Europe\/Rome", "locales": { "it": "Italian", "en": "English" }, "created_at": 1542981950, "updated_at": 1544016407 } } ``` {% endtab %} {% endtabs %} # Blocks {% hint style="info" %} In this section you'll learn how to get all informations about a block or all blocks of your project {% endhint %} {% content-ref url="/pages/-MDJacw02OQQBxrgEAC8" %} [Get Blocks](/api-docs-1/blocks/get-blocks) {% endcontent-ref %} {% content-ref url="/pages/-MDJacY3BAXM\_eu23yMd" %} [Get Block](/api-docs-1/blocks/get-block) {% endcontent-ref %} # Get Blocks {% hint style="info" %} How to obtain project blocks. {% endhint %} {% tabs %} {% tab title="Request" %} `GET https://mburger.cloud/api/blocks` ```bash curl https://mburger.cloud/api/blocks?include=sections&sort=-title&filter[title]=%home,news -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" ``` #### Parameters | Name | Type | Required | Description | | ----------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | skip | int | No | Specify the number of items to skip for pagination. | | take | int | No | Specify the number of items to get for pagination. | | locale | string | No | For multilanguage projects specify the desired locale for elements values. If locale is not provided or found the project fallback will be used. | | include | string | No | Specify which relations to load and include in response. | | sort | string | No | Specify the blocks order. | | filter | string | No | Specify filters on blocks. | | image\_format | string | No | Specify which image dimension to include in response. Values are *thumb*, *medium*, *large* and *original*. Default is *medium*. | | force\_locale\_fallback | boolean | No | If true and the requested locale is empty, the fallback locale is returned. Default false. | #### Includes | Name | Description | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | sections | This relation will include all sections of each block. You can also send *sections.elements* to also obtain all the elements of every section in a single API call. Note that this will impact the performance. | | structure | This relation will include all elements that define the structure of block. | #### Sort | Name | Default | Description | | ----- | ------- | -------------------- | | id | Yes | Sort by id. | | title | No | Sort by title field. | | order | No | Sort by order field. | #### Filters | Name | Exact | Description | | ------------ | ----- | ------------------------ | | id | Yes | You can filter by id. | | title | No | You can filter by title. | | {% endtab %} | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0, "body": { "meta": { "from": 0, "to": 2, "total": 2 }, "items": [ { "id": 2, "order": 1, "title": "News", "subtitle": null, "url_title": "news", "is_single": false, "sections": [ { "id": 1, "order": 1, "all_locales": true, "visible": true, "in_evidence": false, "available_at": 1543395018, "updated_at": 1546599688 }, { "id": 2, "order": 2, "all_locales": true, "visible": true, "in_evidence": false, "available_at": 1543395063, "updated_at": 1546599688 } ] }, { "id": 1, "order": 1, "title": "App Home", "subtitle": null, "url_title": "app-home", "is_single": false, "sections": [ { "id": 3, "order": 3, "all_locales": true, "visible": true, "in_evidence": false, "available_at": 1543395081, "updated_at": 1546599688 } ] } ] } } ``` {% endtab %} {% endtabs %} # Get Block {% hint style="info" %} How to obtain a specific block. {% endhint %} {% tabs %} {% tab title="Request" %} `GET https://mburger.cloud/api/blocks/` ```bash curl https://mburger.cloud/api/blocks/?locale=en -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" ``` #### URL Parameters | Name | Type | Required | Description | | ---- | ---- | -------- | ----------- | | id | int | Yes | Block id. | #### Parameters | Name | Type | Required | Description | | ----------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | locale | string | No | For multilanguage projects specify the desired locale for elements values. If locale is not provided or found the project fallback will be used. | | include | string | No | Specify which relations to load and include in response. | | image\_format | string | No | Specify which image dimension to include in response. Values are *thumb*, *medium*, *large* and *original*. Default is *medium*. | | force\_locale\_fallback | boolean | No | If true and the requested locale is empty, the fallback locale is returned. Default false. | #### Includes | Name | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | sections | This relation will include all sections of each block. You can also send sections.elements to also obtain all the elements of every section in a single API call. Note that this will impact the performance. | | structure | This relation will include all elements that define the structure of block. | | {% endtab %} | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0, "body": { "id": 1, "order": 1, "title": "Home", "subtitle": null, "url_title": "home", "is_single": false } } ``` {% endtab %} {% endtabs %} # Sections {% hint style="info" %} In this section you'll learn how to get, create and delete sections of a block of your project. {% endhint %} {% content-ref url="/pages/-MDJyquuJegeu7Y51DyE" %} [Get Sections](/api-docs-1/sections/get-sections) {% endcontent-ref %} {% content-ref url="/pages/-MDJyqaWZH8Y0qfy2r0z" %} [Get Section](/api-docs-1/sections/get-section-1) {% endcontent-ref %} {% content-ref url="/pages/-MDJyq8VRIagiHz5uo0L" %} [Create Section](/api-docs-1/sections/create-section) {% endcontent-ref %} {% content-ref url="/pages/-MDJypinFegK8Ye51sij" %} [Update Section](/api-docs-1/sections/update-section) {% endcontent-ref %} {% content-ref url="/pages/-MDJynNK6z9BWnR9PxfV" %} [Delete Section](/api-docs-1/sections/delete-section) {% endcontent-ref %} # Get Sections {% hint style="info" %} How to obtain project sections of a block. {% endhint %} {% tabs %} {% tab title="Request" %} `GET https://mburger.cloud/api/blocks//sections` ```bash curl https://mburger.cloud/api/blocks//sections?include=elements&sort=-id&filter[value]=%home,news|paper&skip=0&take=2 -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" ``` #### URL Parameters | Name | Type | Required | Description | | ---- | ---- | -------- | ----------- | | id | int | Yes | Block id. | #### Parameters | Name | Type | Required | Description | | ----------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | skip | int | Yes | Specify the number of items to skip for pagination. | | take | int | Yes | Specify the number of items to get for pagination. | | locale | string | No | For multilanguage projects specify the desired locale for elements values. If locale is not provided or found the project fallback will be used. | | force\_locale\_fallback | boolean | No | If true and the requested locale is empty, the fallback locale is returned. Default false. | | include | string | No | Specify which relations to load and include in response. | | sort | string | No | Specify the sections order. | | filter | string | No | Specify filters on sections. | | image\_format | string | No | Specify which image dimension to include in response. Values are *thumb*, *medium*, *large* and *original*. Default is *medium*. | | distance | string | No | With this parameter and providing your latitude and longitude the distance between you and every section is added in the response. Example: distance=42.24234,13.543344 | #### Includes | Name | Description | | -------- | ------------------------------------------------------------------ | | elements | This relation will include all elements of each section. | | beacons | This relation will include all beacons associated to each section. | #### Sort | Name | Default | Description | | ------------- | ------- | ---------------------------- | | id | No | Sort by id. | | order | No | Sort by order field. | | available\_at | Yes | Sort by available\_at field. | #### Filters | Name | Exact | Description | | ------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | id | Yes | You can filter by id, or a list of comma-separated ids. | | subscription | No | You can filter sections based on Stripe subscription state. Values are *all*, *active*, *inactive*. | | relation | No | You can filter sections based on their relations. | | value | No | You can filter only sections that have specific `value` in their elements. You can pass multiple parameters by passing a comma separated list of values. If you need to filter sections based only on a specific element you can use this syntax `element_name\|search_string` | | geofence | No | You can filter only sections that have elements with a location inside a specific geofence. It requires a string of comma-separated coordinate values representing a rectangle of a map, composed as *NE latitude, SW latitude, NE longitude, SW longitude*. | | {% endtab %} | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0, "body": { "meta": { "from": 0, "to": 2, "total": 10 }, "items": [ { "id": 1, "order": 1, "all_locales": false, "visible": true, "in_evidence": false, "available_at": 1546599965, "updated_at": 1546599966, "elements": { "title": { "id": 2, "name": "title", "type": "text", "order": 1, "options": null, "locale": "en", "value": "Main Home" }, "image": { "id": 3, "name": "image", "type": "image", "order": 2, "options": null, "locale": "en", "value": [ { "id": 1, "url": "https://cdn.mburger.cloud/storage/1/conversions/image-medium.jpg", "size": 45166, "mime_type": "image/jpeg" } ] }, "content": { "id": 4, "name": "content", "type": "textarea", "order": 3, "options": null, "locale": "en", "value": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer nec nisi et sapien tincidunt sodales." } } } ] } } ``` {% endtab %} {% endtabs %} # Get Section {% hint style="info" %} How to obtain a section. You can use the section ID or the slug. {% endhint %} {% tabs %} {% tab title="Request" %} `GET https://mburger.cloud/api/sections/` ```bash curl https://mburger.cloud/api/sections/?include=elements -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" ``` #### URL Parameters | Name | Type | Required | Description | | ---------- | ----------- | -------- | -------------------------------------------- | | id-or-slug | int, string | Yes | Section id or the value of the slug element. | {% hint style="info" %} If you are using the slug (and the project has Multi-language enabled) make sure to include the correct locale in the request. {% endhint %} #### Parameters | Name | Type | Required | Description | | ----------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | locale | string | No | For multi-language projects, specify the desired locale for elements values. If locale is not provided or found the project fallback will be used. | | force\_locale\_fallback | boolean | No | If true and the requested locale is empty, the fallback locale is returned. Default false. | | include | string | No | Specify which relations to load and include in response. | | image\_format | string | No | Specify which image dimension to include in response. Values are *thumb*, *medium*, *large* and *original*. Default is *medium*. | | use\_slug | string | No | If true forces MBurger to use the slug. | | distance | string | No | With this parameter and providing your latitude and longitude the distance between you and every section is added in the response. Example: distance=42.24234,13.543344 | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0, "body": { "id": 1, "order": 1, "all_locales": false, "visible": true, "in_evidence": false, "available_at": 1546599965, "updated_at": 1546599966, "elements": { "title": { "id": 2, "name": "title", "type": "text", "order": 1, "options": null, "locale": "en", "value": "Main Home" }, "image": { "id": 3, "name": "image", "type": "image", "order": 2, "options": null, "locale": "en", "value": [ { "id": 1, "url": "https://cdn.mburger.cloud/storage/1/conversions/image-medium.jpg", "size": 45166, "mime_type": "image/jpeg" } ] }, "content": { "id": 4, "name": "content", "type": "textarea", "order": 3, "options": null, "locale": "en", "value": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer nec nisi et sapien tincidunt sodales." } } } } ``` {% endtab %} {% endtabs %} # Create Section {% hint style="info" %} How to create a new section. {% endhint %} {% hint style="warning" %} Ensure to have read and write permissions. {% endhint %} You'll **need to supply a list of parameters whose name matches the name of the section elements**. For each element, you should give a value accordingly, or else the field would remain empty. {% hint style="info" %} You can find a list of all available elements in the [Available Data Types](https://docs.mburger.cloud/api-docs/going-deeper/available-elements) section! {% endhint %} This API accepts an arbitrary number of parameters. An overview on how to send data is present at [Common](https://app.gitbook.com/@mumble/s/mburger/~/drafts/-MDTbXsvnf7qyBZL7tcv/api-docs/common) section. {% hint style="warning" %} You'll always need to supply the locale in the elements key, even if your project has the Multi-language feature disabled. {% endhint %} For example, if you wish to populate a section that has the following elements: * Title * Description * Image * Link The list of parameters for a single locale (for example, Italian `[it]`) should be: * `elements[it][title]` * `elements[it][description]` * `elements[it][image][0]` * `elements[it][link]` {% hint style="info" %} As you can see, every key of an element **must** be in the form of :small\_blue\_diamond: `elements[LOCALE][ELEMENT_NAME]` {% endhint %} {% hint style="info" %} As you can see, every key of a media element (*image*, *audio*, *video*, *document*, *file*) **must** be in the form of :small\_blue\_diamond:`elements[LOCALE][ELEMENT_NAME][INDEX]` Even if you add just a single image to a media element, it will always be considered as an array. An overview on how to send media files is presented in the [Multipart](https://docs.mburger.cloud/api-docs/common/post-bodies) section. {% endhint %} {% hint style="info" %} Instead ***relation*** elements doesn't require a locale so the key **must** be in the form of :small\_blue\_diamond:`relation[BLOCK_INDEX]` {% endhint %} This API assigns the section creator based on which auth headers are present. If the **mobile** auth header is present the creator is the mobile user, otherwise it will be assigned to **project**. {% tabs %} {% tab title="Request" %} `POST https://mburger.cloud/api/blocks//sections` ```bash curl https://mburger.cloud/api/blocks//sections -X POST -H "Accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" -d '' ``` #### URL Parameters | Name | Type | Required | Description | | ---- | ---- | -------- | ----------- | | id | int | Yes | Block id | #### Parameters The parameters to create a section will depend on which elements the section is made of and how many locales are present. | Name | Type | Required | Description | | -------- | ------- | -------- | ---------------------------- | | order | int | No | To specify an order | | evidence | boolean | No | Enable in\_evidence flag | | elements | array | Yes | An Array of block's elements | {% hint style="info" %} If evidence is true, is possible to set other two parameters: {% endhint %} | Name | Type | Required | Description | | --------------- | ------- | -------- | ------------------------ | | evidence\_title | int | No | To specify an order | | evidence\_image | boolean | No | Enable in\_evidence flag | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ``` { "status_code": 0, "body": { "id": 2, "order": 1, "all_locales": true, "visible": true, "in_evidence": false, "available_at": 1548343787, "updated_at": 1548343787 } } ``` {% endtab %} {% endtabs %} # Update Section {% hint style="info" %} How to update a section. {% endhint %} All the rules discussed on the Create Section part must be used also with this API. {% hint style="info" %} You don't need to update all elements of a section in this call. If you wish, you can only update some of them, all parameters are optional. {% endhint %} {% hint style="warning" %} Note that media file elements will be added to preexisting media. If you wish to replace a media element you should **first delete it**, **then do a section update**. {% endhint %} {% tabs %} {% tab title="Request" %} `POST https://mburger.cloud/api/sections//update` ```bash curl https://mburger.cloud/api/sections//update -X POST -H "Accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" -d '' ``` #### URL Parameters | Name | Type | Required | Description | | ---- | ----------- | -------- | -------------------------------------------- | | id | int, string | Yes | Section id or the value of the slug element. | {% hint style="info" %} If you are using the slug (and the project has Multi-language enabled) make sure to include it in the request the correct locale. {% endhint %} #### Parameters The parameters to update a section will depend on which elements the section is made of and how many locales are present. | Name | Type | Required | Description | | ------------ | ---- | -------- | ------------------- | | order | int | No | To specify an order | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0 } ``` {% endtab %} {% endtabs %} # Delete Section How to delete a section. {% hint style="info" %} Every deleted section by API will be stored in the trash. From MBurger web app is possible to restore the section or to delete it permanently. {% endhint %} {% hint style="warning" %} Ensure to have delete permissions {% endhint %} {% tabs %} {% tab title="Request" %} `DELETE https://mburger.cloud/api/sections/` ```bash curl https://mburger.cloud/api/sections/ -X DELETE -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" ``` #### URL Parameters | Name | Type | Required | Description | | ------------ | ---- | -------- | ----------- | | id | int | Yes | Section id. | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0 } ``` {% endtab %} {% endtabs %} # Media {% hint style="info" %} In this section you'll learn how to manage media of your project. {% endhint %} {% content-ref url="/pages/-MDK-8Iqo-tYjn2bkoh9" %} [Get All Media](/api-docs-1/media/get-all-media) {% endcontent-ref %} {% content-ref url="/pages/-MQw2vGREnSe82E5qJjw" %} [Upload Media](/api-docs-1/media/upload-media) {% endcontent-ref %} {% content-ref url="/pages/-MDK-7IKKg\_BFT2fCL9f" %} [Get Media](/api-docs-1/media/get-media) {% endcontent-ref %} {% content-ref url="/pages/-MDK-6eut60YITchyM7I" %} [Delete Media](/api-docs-1/media/delete-media) {% endcontent-ref %} # Get All Media {% hint style="info" %} To obtain all media of a project (Media section) {% endhint %} {% tabs %} {% tab title="Request" %} `GET https://mburger.cloud/api/media` ```bash curl https://mburger.cloud/api/media -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" ``` #### Parameters | Name | Type | Required | Description | | ------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- | | image\_format | string | No | Specify which image dimension to include in response. Values are *thumb*, *medium*, *large* and *original*. Default is *medium*. | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0, "body": [ { "id": 1, "url": "https://cdn.mburger.cloud/storage/1/conversions/image-medium.jpg", "size": 12302, "mime_type": "image/jpeg" } ] } ``` {% endtab %} {% endtabs %} # Upload Media {% hint style="info" %} How to upload a media {% endhint %} {% tabs %} {% tab title="Request" %} `POST https://mburger.cloud/api/media` ```bash curl https://mburger.cloud/api/media -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" ``` #### Parameters | Name | Type | Required | Description | | ------------ | ----- | -------- | ------------------------------------------- | | media | array | Yes | An array of media to upload to the project. | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ``` { "status_code": 0, 0 => { "id": 2 "uuid": "uuid-of-the-media" "url": "http://example.test/storage/1/image.jpeg" "size": 695 "file_name": "image.jpeg" "mime_type": "image/jpeg" } } ``` {% endtab %} {% endtabs %} # Get Media {% hint style="info" %} How to get a media {% endhint %} {% tabs %} {% tab title="Request" %} `GET https://mburger.cloud/api/media/` ```bash curl https://mburger.cloud/api/media/ -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" ``` #### URL Parameters | Name | Type | Required | Description | | ---- | ---- | -------- | ----------- | | id | int | Yes | Media id. | #### Parameters | Name | Type | Required | Description | | ------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- | | image\_format | string | No | Specify which image dimension to include in response. Values are *thumb*, *medium*, *large* and *original*. Default is *medium*. | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0, "body": { "id": 1, "url": "https://cdn.mburger.cloud/storage/1/conversions/image-medium.jpg", "size": 12302, "mime_type": "image/jpeg" } } ``` {% endtab %} {% endtabs %} # Delete Media {% hint style="info" %} How to delete a media {% endhint %} {% hint style="warning" %} Ensure to have delete permissions {% endhint %} {% tabs %} {% tab title="Request" %} `DELETE https://mburger.cloud/api/media/` ```bash curl https://mburger.cloud/api/media/ -X DELETE -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" ``` #### URL Parameters | Name | Type | Required | Description | | ------------ | ---- | -------- | ----------- | | id | int | Yes | Media id. | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0 } ``` {% endtab %} {% endtabs %} # Integrations / Extensions The table below contains all available features that can be enabled in project settings. | Feature | Description | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Analytics | All metrics of your project in a single page on MBurger dashboard. | | Push Notifications | Allows you to send or schedule push notifications to your mobile devices. | | Beacons | You can associate beacons to your sections. | | Multi-language | This feature adds multi-language to you project. You can add all languages you’d like. | | [Authentication Provider](/api-docs-1/integrations-extensions/users) | Feature that allows you to manage end-users users for your project, like mobile apps users. | | [Live Messages](/api-docs-1/integrations-extensions/misc) | You can send live messages from clients and see them live in the MBurger dashboard. | | Shopify | You can organize menu collections of a Shopify account and complete an order using Stripe. | # Authentication Provider MBurger could be used also as an external authentication provider, enabling you to register and log-in/out your users, store store their informations and manage their sessions. In this section you'll learn how to create mobile users, have them sign up, and manage their profiles. {% hint style="info" %} Be aware that **we are not talking about dashboard users** but end-users of a website or an app that uses the MBurger platform {% endhint %} {% content-ref url="/pages/-MDJVhIV-M8zqq7YKe\_Q" %} [Registration](/api-docs-1/integrations-extensions/users/register) {% endcontent-ref %} {% content-ref url="/pages/-MDJXmIdbHgyxkuBsdJv" %} [Login](/api-docs-1/integrations-extensions/users/login) {% endcontent-ref %} {% content-ref url="/pages/-MDJXm1kLE3L8fdk1\_62" %} [Logout](/api-docs-1/integrations-extensions/users/logout) {% endcontent-ref %} {% content-ref url="/pages/-MDJXlkd8Fb71OIo2h0C" %} [Get Profile](/api-docs-1/integrations-extensions/users/get-profile) {% endcontent-ref %} {% content-ref url="/pages/-MDJXlTBQDx0c9Cebr9r" %} [Update Profile](/api-docs-1/integrations-extensions/users/update-profile) {% endcontent-ref %} {% content-ref url="/pages/-MDJXl7\_QUptCqRkdw-z" %} [Delete Profile](/api-docs-1/integrations-extensions/users/delete-profile) {% endcontent-ref %} {% content-ref url="/pages/-MDJXkd6Mq-UW9qlGH8l" %} [Change Password](/api-docs-1/integrations-extensions/users/change-password) {% endcontent-ref %} {% content-ref url="/pages/-MDJXk30wkL3vLPEcYns" %} [Forgot Password](/api-docs-1/integrations-extensions/users/forgot-password) {% endcontent-ref %} # Registration {% hint style="info" %} To register a new user using the **mobile** provider {% endhint %} {% tabs %} {% tab title="Request" %} `POST https://mburger.cloud/api/register` ```bash curl https://mburger.cloud/api/register -X POST -H "Accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" -d '' ``` #### Parameters | Name | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------- | | name | string | Yes | The user name | | surname | string | Yes | The user surname | | email | string | Yes | User email | | password | string | Yes | Password | | phone | string | No | The user phone number | | gender | string | No | The user gender | | image | string | No | Base64 encoded image | | contracts | JSON | No | JSON array of contracts accepted by user | | data | JSON | No | JSON object/array that contains custom data | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0 } ``` {% endtab %} {% endtabs %} # Login {% hint style="info" %} This will show you how to log in a user using the **mobile** provider. It will give you a JWT token which will be needed for the following APIs. {% endhint %} {% hint style="warning" %} If you try to authenticate a user by email, but the email was previously registered through Facebook, Google or Apple, MBurger will throw out an error as the user is already registered with "email" mode. {% endhint %} {% hint style="warning" %} To know more about the social token please refer to [Facebook](https://developers.facebook.com/docs/facebook-login), [Google](https://developers.google.com/identity) or [Apple](https://developer.apple.com/sign-in-with-apple/) {% endhint %} {% tabs %} {% tab title="Request" %} `POST https://mburger.cloud/api/login` ```bash curl https://mburger.cloud/api/login -X POST -H "Accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" -d '' ``` #### Parameters | Name | Type | Required | Description | | --------------- | ------ | -------- | --------------------------------------------------------------------------- | | email | string | No | Email | | password | string | No | Password | | mode | string | Yes | Auth mode : *email, facebook, google, apple* | | facebook\_token | string | No | Facebook token obtained from Facebook SDK, **required if mode = facebook**. | | google\_token | string | No | Google token, obtained from Google SDK, **required if mode = google**. | | apple\_token | string | No | Apple token, obtained from Apple SDK, **required if mode = apple**. | | {% endtab %} | | | | {% tab title="Response" %} When succesful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0, "body": { "access_token": "JWT", "token_type": "Bearer" } } ``` {% endtab %} {% endtabs %} # Logout {% hint style="info" %} How to log out a user using the **mobile** provider {% endhint %} {% tabs %} {% tab title="Request" %} `POST https://mburger.cloud/api/logout` ```bash curl https://mburger.cloud/api/logout -X POST -H "Accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" ``` #### Parameters This API has no parameters. {% endtab %} {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0 } ``` {% endtab %} {% endtabs %} # Get Profile {% hint style="info" %} How to get a user profile {% endhint %} {% tabs %} {% tab title="Request" %} `GET https://mburger.cloud/api/profile` ```bash curl https://mburger.cloud/api/profile -H "Accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" -H "Authorization: Bearer" ``` #### Parameters This API has no parameters. {% endtab %} {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0, "body": { "id": 1, "name": "Name", "surname": "Surname", "email": "name.surname@mail.com", "fb_id": null, "auth_mode": "email", "data": [], "stripe_id": null, "card_brand": null, "card_last_four": null, "trial_ends_at": null, "subscriptions": [], "purchases": [], "published_sections": [], "contracts": [] } } ``` {% endtab %} {% endtabs %} # Update Profile {% hint style="info" %} How to update a user profile {% endhint %} {% tabs %} {% tab title="Request" %} `POST https://mburger.cloud/api/profile/update` ```bash curl https://mburger.cloud/api/profile/update -X POST -H "Accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" -H "Authorization: Bearer " -d '' ``` #### Parameters | Name | Type | Required | Description | | ------- | ------ | -------- | ------------------------------------------- | | name | string | Yes | The user name | | surname | string | Yes | The user surname | | data | JSON | No | JSON object/array that contains custom data | Parameters list is in the Register parameters table. {% endtab %} {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0, "body": { "id": 1, "name": "Name", "surname": "Surname", "email": "name.surname@mail.com", "fb_id": null, "auth_mode": "email", "data": { "key": "value" }, "stripe_id": null, "card_brand": null, "card_last_four": null, "trial_ends_at": null, "subscriptions": [], "purchases": [], "published_sections": [], "contracts": [] } } ``` {% endtab %} {% endtabs %} # Delete Profile {% hint style="info" %} How to delete a user profile {% endhint %} {% hint style="warning" %} Please be aware that this operation can not be undone {% endhint %} {% tabs %} {% tab title="Request" %} `DELETE https://mburger.cloud/api/profile/delete` ```bash curl https://mburger.cloud/api/profile/delete -X DELETE -H "Accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" -H "Authorization: Bearer " ``` #### Parameters This API has no parameters. {% endtab %} {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0 } ``` {% endtab %} {% endtabs %} # Change Password {% hint style="info" %} How to change the password of a logged user using the **mobile** provider {% endhint %} {% tabs %} {% tab title="Request" %} `POST https://mburger.cloud/api/change-password` ```bash curl https://mburger.cloud/api/change-password -X POST -H "Accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" -H "Authorization: Bearer " -d '' ``` #### Parameters | Name | Type | Required | Description | | ------------- | ------ | -------- | ---------------- | | old\_password | string | Yes | The old password | | new\_password | string | Yes | The new password | | email | string | Yes | The user email | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0 } ``` {% endtab %} {% endtabs %} # Forgot Password {% hint style="info" %} How to recover the password of a user using the **mobile** provider. {% endhint %} > A new password will be generated and sent by email {% tabs %} {% tab title="Request" %} `POST https://mburger.cloud/api/forgot-password` ```bash curl https://mburger.cloud/api/forgot-password -X POST -H "Accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" -d '' ``` #### Parameters | Name | Type | Required | Description | | ------------ | ------ | -------- | ----------- | | email | string | Yes | Email | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0 } ``` {% endtab %} {% endtabs %} # Live Messages {% hint style="info" %} In this section you'll learn how to create, send and delete Live Messages {% endhint %} {% content-ref url="/pages/-MDK0YW1brBxsWd6jULN" %} [Get All Live Messages](/api-docs-1/integrations-extensions/misc/get-all-live-messages) {% endcontent-ref %} {% content-ref url="/pages/-MDK0Y7mvTl0gpUNWp\_G" %} [Send Live Message](/api-docs-1/integrations-extensions/misc/send-live-message) {% endcontent-ref %} {% content-ref url="/pages/-MDK0XeN-5Kq5CAdI37L" %} [Delete Live Message](/api-docs-1/integrations-extensions/misc/delete-live-message) {% endcontent-ref %} # Get All Live Messages {% hint style="info" %} How to obtain all live messages {% endhint %} {% tabs %} {% tab title="Request" %} `GET https://mburger.cloud/api/live-messages` ```bash curl https://mburger.cloud/api/live-messages -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" ``` #### Parameters | Name | Type | Required | Description | | ------------ | ---- | -------- | -------------------------------- | | skip | int | No | Messages to skip for pagination. | | take | int | No | Messages to take for pagination. | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0, "body": [ { "id": 1, "text": "Message 1", "sender_name": null, "created_at": 1549365553 }, { "id": 2, "text": "Message 2", "sender_name": "Mumble", "created_at": 1549365562 } ] } ``` {% endtab %} {% endtabs %} # Send Live Message {% hint style="info" %} How to send a live message {% endhint %} {% tabs %} {% tab title="Request" %} `POST https://mburger.cloud/api/send-live-message` ```bash curl https://mburger.cloud/api/send-live-message -X POST -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" ``` #### Parameters | Name | Type | Required | Description | | ---------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- | | text | string | Yes | Message text. | | sender\_name | int | No | Sender name. | | mobile\_user\_id | int | No | You can associate a mobile user id, which is useful when you send messages from clients like the app. | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0 } ``` {% endtab %} {% endtabs %} # Delete Live Message {% hint style="info" %} How to delete a live message {% endhint %} {% hint style="warning" %} Ensure to have delete permissions {% endhint %} {% tabs %} {% tab title="Request" %} `DELETE https://mburger.cloud/api/live-messages/` ```bash curl https://mburger.cloud/api/live-messages/ -X DELETE -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" ``` #### URL Parameters | Name | Type | Required | Description | | ------------ | ---- | -------- | ------------------------- | | id | int | Yes | Live message id to delete | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0 } ``` {% endtab %} {% endtabs %} # In-App Subscriptions Offer a seamless experience for digital subscriptions in your apps. In-app purchase APIs provide a simple, powerful way to implement auto-renewable subscriptions in your apps. In this part we will discuss how to implement in app subscriptions for iOS and Android. {% hint style="info" %} In order to handle all logic of renewing subscriptions, you need to set the iOS webhook to `https://mburger.cloud/inapp-ios/webhook` and Android to `https://mburger.cloud/inapp-android/webhook` {% endhint %} For any further details please refer to the official documentation iOS and Android. # InApp Subscription {% hint style="info" %} How to create a new iOS/Android subscription for the logged user {% endhint %} {% tabs %} {% tab title="Request" %} `POST https://mburger.cloud/api/subscriptions-in-app` ```bash curl https://mburger.cloud/api/subscriptions-in-app -X POST -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" -H "Authorization: Bearer " -d '' ``` #### Parameters | Name | Type | Required | Description | | ------------ | ------ | -------- | ----------------------------------------------------------- | | os | string | Yes | The client platform. Available values are *ios*, *android*. | | subscription | string | Yes | The subscription identifier. | | receipt | string | Yes | The receipt provided by mobile stores. | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0 } ``` {% endtab %} {% endtabs %} # Resume InApp Subscription {% hint style="info" %} How to resume a canceled/paused subscription for the logged user {% endhint %} {% tabs %} {% tab title="Request" %} `POST https://mburger.cloud/api/subscriptions-in-app/resume` ```bash curl https://mburger.cloud/api/subscriptions-in-app/resume -X POST -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" -H "Authorization: Bearer " -d '' ``` #### Parameters | Name | Type | Required | Description | | ------------ | ------ | -------- | ------------------------ | | subscription | string | Yes | Subscription identifier. | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0 } ``` {% endtab %} {% endtabs %} # Shopify With the Shopify MBurger integration you're able to manage your collections, define their order and embed collections inside another collection to build your custom menu. # Create a Shopify private app To begin you need to create a private app in your Shopify store: * Go in the Apps section of your shop * Click on Manage private apps at the end of the page * Click on Create private app In the "Storefront API" section, click on "Allow this app to access your storefront data using the Storefront API." Enable the following permissions: * Read products, variants and collections \[read] * Read product tags \[read] # Enable Shopify in MBurger In the MBurger dashboard go to Control Panel -> Settings and enable the Shopify integration. ![](/files/-MLDpzvxBVcIyYnHQ75E) Insert the name of your Shopify store and the key and secret of the private app.\ The name of the store needs to be insertted without the extension myshopify.com, if the url of your store is "mystore.myshopify.com" insert only "mystore" After you enable you will unlock the Shopify section in the lateral menu and the "Collections Editor". ![](/files/-MLDrFBY_peKHkXVaSQf) # Collections Editor Here you can organize the collections of your Shopify store and choose a structure, using drag and drop. To load the collections you have to click on the "Reload" button, this will refresh the collections saved in MBurger and add new collections that you've added on Shopify. This will not cancel all the work you've done previously, the structure that you have built will remaiin untouched. Once you've build your collection tree save it with the "Save" button. The structure you've created will retrurn in the `project` api. ```javascript { ... "shopify_menu": [ { "id": collection_id, "image": { "src": collection_image } "text": collection_name, "children": [ {...}, {...} ] } ] ... } ``` The children array is an array of objects with the same structure of the collection. # Stripe In this part, we will discuss how to implement payment API connected with a Stripe merchant account. Before you read this part, we’d suggest getting comfortable with [Stripe](https://stripe.com) and its features by creating an account and obtaining an API Key. You'll need to put this in the Mburger dashboard in the section, Settings. {% hint style="info" %} In order to handle all logic of renewing subscriptions, you need to set the Stripe webhook to [`https://mburger.cloud/stripe/webhook`](https://mburger.cloud/stripe/webhook) {% endhint %} This API will use objects generated by Stripe API in response. {% content-ref url="/pages/-MDKJI2LDrb8o1b9e0jN" %} [Create Customer](/api-docs-1/integrations-extensions/stripe/create-customer) {% endcontent-ref %} {% content-ref url="/pages/-MDKJJzbf2KBYmR6NLu4" %} [Get Cards](/api-docs-1/integrations-extensions/stripe/get-cards) {% endcontent-ref %} {% content-ref url="/pages/-MDKJJqIUS5Wqc-pTPna" %} [Create Card](/api-docs-1/integrations-extensions/stripe/create-card) {% endcontent-ref %} {% content-ref url="/pages/-MDKJJgJNp0\_qvU1plig" %} [Make Default](/api-docs-1/integrations-extensions/stripe/make-default) {% endcontent-ref %} {% content-ref url="/pages/-MDKJJatPA6hYs8muDHA" %} [Delete Card](/api-docs-1/integrations-extensions/stripe/delete-card) {% endcontent-ref %} {% content-ref url="/pages/-MDKJJHAXzD-IkQ3TQil" %} [Subscription](/api-docs-1/integrations-extensions/stripe/subscription) {% endcontent-ref %} {% content-ref url="/pages/-MDKJNei8qJEdCnrFJ2E" %} [Cancel Subscription](/api-docs-1/integrations-extensions/stripe/cancel-subscription) {% endcontent-ref %} {% content-ref url="/pages/-MDKJNUQUhvIDgQPd6dO" %} [Resume Subscription](/api-docs-1/integrations-extensions/stripe/resume-subscription) {% endcontent-ref %} {% content-ref url="/pages/-MDKKAFy6y9vyNPx\_FaP" %} [Payment](/api-docs-1/integrations-extensions/stripe/payment) {% endcontent-ref %} # Create Customer {% hint style="info" %} This API will create a new Stripe customer based on the current **mobile user** {% endhint %} It isn't required for other payments API since the customer will be automatically created if not present {% tabs %} {% tab title="Request" %} `POST https://mburger.cloud/api/customers` ```bash curl https://mburger.cloud/api/customers -X POST -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" -H "Authorization: Bearer " ``` #### Parameters This API has no parameters. {% endtab %} {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0, "body": { "id": "cus_xxxxxxxxxxxxxx", "object": "customer", "account_balance": 0, "created": 1549288732, "currency": null, "default_source": null, "delinquent": false, "email": "name.surname@mail.com", "sources": { "object": "list", "data": [], "has_more": false, "total_count": 0, "url": "/v1/customers/cus_xxxxxxxxxxxxxx/sources" }, "subscriptions": { "object": "list", "data": [], "has_more": false, "total_count": 0, "url": "/v1/customers/cus_xxxxxxxxxxxxxx/subscriptions" } } } ``` {% endtab %} {% endtabs %} # Get Cards {% hint style="info" %} How to get all saved cards for logged user {% endhint %} {% tabs %} {% tab title="Request" %} `GET https://mburger.cloud/api/cards` ```bash curl https://mburger.cloud/api/cards -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" -H "Authorization: Bearer " ``` #### Parameters This API has no parameters. {% endtab %} {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0, "body": [ { "id": "card_xxxxxxxxxxxxxxxxxxxxxxxx", "brand": "Visa", "exp_month": 4, "exp_year": 2024, "last4": "4242", "default": true } ] } ``` {% endtab %} {% endtabs %} # Create Card {% hint style="info" %} How to create a new Stripe card {% endhint %} The new card will be set as the default payment method automatically by Stripe {% tabs %} {% tab title="Request" %} `POST https://mburger.cloud/api/cards` ```bash curl https://mburger.cloud/api/cards -X POST -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" -H "Authorization: Bearer " ``` #### Parameters | Name | Type | Required | Description | | ------------ | ------ | -------- | --------------------------------- | | token | string | Yes | Token provided by the Stripe SDK. | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0 } ``` {% endtab %} {% endtabs %} # Make Default {% hint style="info" %} How to set the provided Stripe card as default {% endhint %} {% tabs %} {% tab title="Request" %} `GET https://mburger.cloud/api/cards//dafault` ```bash curl https://mburger.cloud/api/cards//dafault -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" -H "Authorization: Bearer " ``` #### URL Parameters | Name | Type | Required | Description | | ------------ | ---- | -------- | ------------------------------------------------------- | | id | int | Yes | Card ID in the format *card\_xxxxxxxxxxxxxxxxxxxxxxxx*. | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0 } ``` {% endtab %} {% endtabs %} # Delete Card {% hint style="info" %} How to delete the provided Stripe card {% endhint %} {% hint style="warning" %} Ensure to have delete permissions {% endhint %} {% tabs %} {% tab title="Request" %} `DELETE https://mburger.cloud/api/cards/` ```bash curl https://mburger.cloud/api/cards/ -X DELETE -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" -H "Authorization: Bearer " ``` #### URL Parameters | Name | Type | Required | Description | | ------------ | ---- | -------- | ------------------------------------------------------- | | id | int | Yes | Card ID in the format *card\_xxxxxxxxxxxxxxxxxxxxxxxx*. | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0 } ``` {% endtab %} {% endtabs %} # Subscription {% hint style="info" %} How to create a new Stripe subscription for the logged user {% endhint %} Calling this API will immediately charge the user (or after the trial has ended). Based on the subscription charge period, it will continue to charge the user. For the subscription lifecycle please refer to [Stripe documentation](https://stripe.com/docs/billing/lifecycle) {% tabs %} {% tab title="Request" %} `POST https://mburger.cloud/api/subscriptions` ```bash curl https://mburger.cloud/api/subscriptions -X POST -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" -H "Authorization: Bearer " -d '' ``` #### Parameters | Name | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- | | subscription | string | Yes | Subscription identifier chosen on Stripe dashboard. | | token | string | No | Source token provided by the Stripe SDK, it is not required if the user is already a customer and wants to use the default card. | | discount\_code | string | No | Identifier of discount code. | | trial\_days | int | No | Number of days before the first charge of the subscription. | | quantity | int | No | Quantity of subscriptions you'll need to subscribe; generally 1 or no data. | | meta | JSON | No | Additional data to save for the subscription. | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0 } ``` {% endtab %} {% endtabs %} # Cancel Subscription {% hint style="info" %} How to cancel an active Stripe subscription for the logged user {% endhint %} {% tabs %} {% tab title="Request" %} `POST https://mburger.cloud/api/subscriptions/cancel` ```bash curl https://mburger.cloud/api/subscriptions/cancel -X POST -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" -H "Authorization: Bearer " -d '' ``` #### Parameters | Name | Type | Required | Description | | ------------ | ------ | -------- | -------------------------------------------------- | | subscription | string | Yes | Subscription identifier from the Stripe dashboard. | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0 } ``` {% endtab %} {% endtabs %} # Resume Subscription {% hint style="info" %} How to resume a canceled/paused Stripe subscription for the logged user {% endhint %} {% tabs %} {% tab title="Request" %} `POST https://mburger.cloud/api/subscriptions/resume` ```bash curl https://mburger.cloud/api/subscriptions/resume -X POST -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" -H "Authorization: Bearer " -d '' ``` #### Parameters | Name | Type | Required | Description | | ------------ | ------ | -------- | -------------------------------------------------- | | subscription | string | Yes | Subscription identifier from the Stripe dashboard. | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0 } ``` {% endtab %} {% endtabs %} # Payment {% hint style="info" %} How to create a new Stripe payment for the logged user {% endhint %} Calling this API will immediately charge the user for the amount of the product. For the billing lifecycle please refer to [Stripe documentation](https://stripe.com/docs/billing/lifecycle) {% tabs %} {% tab title="Request" %} `POST https://mburger.cloud/api/payments` ```bash curl https://mburger.cloud/api/payments -X POST -H "Accept: application/json" -H "X-MBurger-Token: " -H "X-MBurger-Version: 3" -H "Authorization: Bearer " -d '' ``` #### Parameters | Name | Type | Required | Description | | ------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- | | name | string | Yes | Payment identifier chosen on Stripe dashboard. | | amount | int | Yes | Amount to charge for single product. | | quantity | int | Yes | Quantity of products. | | token | string | No | Source token provided by the Stripe SDK, it is not required if the user is already a customer and wants to use the default card. | | meta | JSON | No | Additional data to save for the payment. | | {% endtab %} | | | | {% tab title="Response" %} When successful, a HTTP 200 and JSON like this is returned: ```bash { "status_code": 0 } ``` {% endtab %} {% endtabs %} # Going Deeper {% hint style="success" %} Here you can explore some extra functions that will make your MBurger journey way better! {% endhint %} # Available Data Types (Elements) The following table contains all available elements. | Element | Description | | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Text | Simple text field like a title. | | Textarea | Longer multiline text field like a content or a description. | | Markdown | It's like a textarea but supports all markdown features. | | Checkbox | Checkbox that can assume 2 states. | | Image | An image file. | | Audio | An audio file. | | Video | A video file. | | Document | A readable document file like .txt, .docx, .pptx etc. | | File | A generic file like .zip, .ipa, .apk etc. | | Datetime | Field containing a datetime. | | Address | Text field containing an address with automatic reverse geocoding to retrieve the coordinates. | | Dropdown | Dropdown with multiple choices, of which only one is selectable. | | Multiple | Similar to Dropdown but you can select multiple values. | | Relation | With this element you can create relations between your data. | | SEO | For every section, it is possible to specify SEO meta fields. | | Multiple | With multiple select element you can easily set multiple choices. This component is ideal for add categories inside a blog or segment the clients where you want to spread out your contents. | | Color | With color picker element you can easily choose a color in hex format. | | Custom | With Custom element you can easily add any data to your sections. | ## SEO With the SEO element, it is possible to specify several meta fields such as title, description, keywords and image. In this way, you can take advantage of SEO optimizations performed by search engines to better index your content. An API response example: ```bash "value": { "title": "SEO Title", "keywords": ["Some", "SEO", "keywords"], "description": "SEO Description", "image": { "id": 1, "url": "https://cdn.mburger.cloud/storage/1/conversions/image-medium.jpg", "size": 45166, "mime_type": "image/jpeg" } } ``` ## Slug Slug element is present by default and allows a specification of a textual ID for sections. It can be used to request sections instead of a classic numeric ID. An API response example: ```bash "value": "slug-of-your-section" ``` # Android SDK To initialize the SDK you have to create a token through the [dashboard](https://mburger.cloud/). Click on the settings icon on the top-right and create an API Key specifying the permissions. On your app before doing anything you must initialize the SDK with your API Key by using the `MBurger` class, also you should specify if you are using the development api or the standard API, be aware that different mode means different key, so a "development api key" would not work if you are using standard api. ```kotlin MBurger.initialize("", ); ``` `MBurger.initialize()` also may accept other parameters to control if you want MBurger SDK to cache your requests, you will find all information you need inside the [Javadoc](https://github.com/Mumble-SRL/MBurger/tree/master/Javadoc). Requesting anything from the SDK before initializing will result in an exception, so you shoud initialize on your `onCreate` starting Activity or on your custom `Application` class. ### Client usage Basically you can obtain and use all your project data using 3 classes with public static methods: `MBurgerTasks`, `MBurgerMapper` and `MBurgerApiActionInitializer`. All these classes are used to obtain and map your custom objects from MBurger objects. # Introduction MBurger should be initialized in your App class with an `API KEY`. {% hint style="warning" %} Is essential to initialize MBurger at the start of the application otherwise you won’t be able to use the sdk API. {% endhint %} You can create an API Key by entering the project’s settings and create one with desired permissions. {% hint style="info" %} `MBurger.initialize()` also may accept other parameters to control if you want the SDK to cache your requests, or to use development that is not officially supported, API. {% endhint %} {% hint style="success" %} You will find all the information you need inside the Javadoc. {% endhint %} # Installation {% hint style="info" %} On Android Studio you can add MBurger dependency using gradle via **Maven**. {% endhint %} First add this line to your project **`build.gradle`** file under **`allprojects{repositories{`** ```java maven { url "https://dl.bintray.com/mumbleideas/MBurger-Android/" } ``` Then you just need to add the dependency for MBurger on your app build.gradle file: This one if you want to use the Kotlin version of the SDK **(recommended)**: ```java implementation 'mumble.mburger:android_kt:0.5.11' ``` If you want you can also download or clone the repo, you will find a `MBurger` directory, which contains the client SDK to use MBurger. You can also import **`MBurger`** library inside your Android Studio project and include it adding to your **`settings.gradle`** file, then import into your app adding to your app module **`build.gradle`** file ```java implementation project(':mburger_kt') ``` {% hint style="warning" %} Be aware that MBurger SDK implements: {% endhint %} ```java //In order to support some components on older Android versions implementation 'androidx.legacy:legacy-support-v4:1.0.0' //For installing https certificates on older Android versions implementation 'com.google.android.gms:play-services-base:17.3.0' //For Admin API support implementation 'com.squareup.okhttp3:okhttp:3.14.0' ``` {% hint style="warning" %} Also this SDK requires **AndroidX** support as well as **minimum SDK 4.2** (API 17). {% endhint %} # Initialization In order to use the SDK you should create an API Key, which will let you use MBurger APIs, you can do that on the dashboard settings for your Project and decide key permissions, at minimum it should be "read". If you wish to delete, update or create new sections you should add "write" and "delete" permissions. API Keys can be used for Android apps as well as iOS apps, so you don't really need to create 2 keys for the two OS. On your app before doing anything you must initialize the SDK with your API Key by using the `MBurger` class, also you should specify if you are using the development api or the standard API, be aware that different mode means different key, so a "development api key" would not work if you are using standard api. You can add plugins or leave it `null`. ```kotlin MBurger.initialize("", , , ); ``` `MBurger.initialize()` also may accept other parameters to control if you want MBurger SDK to cache your requests, you will find all information you need inside the [Javadoc](https://github.com/Mumble-SRL/MBurger/tree/master/Javadoc). Requesting anything from the SDK before initializing will result in an exception, so you shoud initialize on your `onCreate` starting Activity or on your custom `Application` class. ### Client usage Basically you can obtain and use all your project data using 3 classes with public static methods: `MBurgerTasks`, `MBurgerMapper` and `MBurgerApiActionInitializer`. All these classes are used to obtain and map your custom objects from MBurger objects. # Fetch for blocks You should use **`MBurgerTasks`** static methods to retrieve data from MBurger dashboard. This class has public static functions that will call asynchronously MBurger API. You have 2 ways to retrieve data from API: * Listener * Actions ## Listener {% hint style="success" %} The **Listener** approach is the easiest one. {% endhint %} With every method of the MBurgerTasks class you should pass the corresponding listener to return data from the function to your control. {% hint style="info" %} All the listeners are inside the **`MBApiResultsListeners`** and all of them are simple interfaces that will return the MBurger object you asked for or an error message. {% endhint %} For example, you should use a **`MBApiProjectResultListener`** (implementing it to your Activity or Fragment or creating a new one runtime) to obtain Project basic data, so the class will implement these methods: ```kotlin @Override fun onProjectApiResult(project: MBProject) { /*API call went well*/ } @Override fun onProjectApiError(error: String) { /*There was an error, you should show it*/ } ``` ## Actions {% hint style="success" %} The **Action** approach is more complicated but more flexible. {% endhint %} It uses **`LocalBroadcastMessages`** to send data from the API to your Activity/Fragment using an Action which your Activity/Fragment is listening to. You can also use this method also if you are doing your own API calls to your server. First you must implement **`MBGenericApiResultListener`** which will automatically implement the method.Java ```kotlin @Override fun onApiResult(response: MBAPIResponse) { } ``` For example, to obtain the blocks and the project you have to follow these few steps: * **Create** a `BroadcastReceiver`. * **Initialize** the BroadcastReceiver in your onResume method with the `MBurgerApiActionInitializer` class specific function. * **Pause** the BroadcastReceiver in your onPause method with the `MBurgerApiActionInitializer` class specific function. * **Call** the task to send the blocks’ request according to the parameters given in this sample. * **Fetch** the blocks from the response variable of `onApiResult`. The code will result: ```kotlin override fun onResume() { super.onResume(); val actions = arrayOf(MBAPIConstants.ACTION_GET_BLOCKS, MBAPIConstants.ACTION_GET_PROJECT) bRec = MBurgerApiActionInitializer.initializeNookoReceiverCustom(this, this, actions) MBurgerTasks.askForProject(this) /**Add custom filters to the API call or leave it null**/ val arrayOfFilters: ArrayList = null /**Inside the blocks returned the “sections” field will be valorized**/ val getSections = true /**Inside the sections the “elements” field will not be valorized (null)**/ val getElements = false MBurgerTasks.askForBlocks(this, arrayOfFilters, getSections, getElements) MBurgerTasks.askForProject(this) } override fun onPause() { super.onPause() MBurgerApiActionInitializer.pauseNookoReceiver(this, bRec) } override fun onApiResult(MBAPIResponse response) { /** Check ApiAction to distinguish the responses**/ if (response.getApiAction().equals(MBAPIConstants.ACTION_GET_BLOCKS)) { if (response.getResult()) { blocks = (ArrayList)response.getPayload().get(MBApiPayloadKeys.key_blocks) /** Once you received the project’s blocks you can draw your menu**/ } else { Log.e(“ERROR RESPONSE API”, “THERE WAS AN ERROR DURING BLOCKS’ LOADING”) } } if(response.getApiAction().equals(MBAPIConstants.ACTION_GET_PROJECT)){ if (response.getResult()) { project = (MBProject)response.getPayload().get(MBApiPayloadKeys.key_project) /** Your code**/ } else { Log.e(“ERROR RESPONSE API”, “THERE WAS AN ERROR DURING BLOCKS’ LOADING”) } } } ``` Note that you can check the ApiAction to distinguish the different responses, and you will find all responses inside the **`MBAPIConstants`** class. {% hint style="info" %} In case you previously initialized a BroadcastReceiver only for blocks this check is useless. {% endhint %} This is an example of a single-action BroadcastReceiver initialization (for blocks) Single action initializationJava ```kotlin override fun onResume() { super.onResume(); bRec = MBurgerApiActionInitializer.initializeNookoReceiverForBlocks(this, this); } ``` # Fetch sections from blocks Setting the specific block\_id, it is possible to obtain the corresponding section’s data. If you want, you can include whether or not you want to filter the elements of the section by adding an array of filters. The process to reach the result is the same as the blocks’ example: * **Create, initialize** and **pause** the BroadcastReceiver (using “forSections” method). * **Call** the task. * **Fetch** the sections from the response of onApiResult. Your code should be like this: ```kotlin override fun onResume() { super.onResume() /**Create your sections’ receiver**/ bRec = MBurgerApiActionInitializer.initializeNookoReceiverForSections(this, this) /**Add custom filters to the API call or leave it null**/ val arrayOfFilters : ArrayList = null /**Id of the block you wish to retrieve sections**/ val block_id = block.getId() /**Inside the sections the “elements” field will be valorized**/ val getElements = true /**Call sections’ API**/ MBurgerTasks.askForSections(this, block_id, arrayOfFilters, getElements) } override fun onPause() { super.onPause() MBurgerApiActionInitializer.pauseNookoReceiver(getActivity(), bRec) } override fun onApiResult(response: MBAPIResponse ) { if (response.getResult()) { val sections = response.getPayload().get(MBApiPayloadKeys.key_sections) as ArrayList if (sections.size() > 0) { //Your code } else { Log.w(“WARNINGS HOME”, “THE HOME’ S SECTION IS EMPTY”) } } else { Log.e(“ERROR RESPONSE API”, “THERE WAS AN ERROR DURING HOME’ S LOADING”) } } ``` {% hint style="warning" %} If you specify more filters of the same type inside the array, **only the last one of those type will be considered**. {% endhint %} # Mapping to custom objects {% hint style="info" %} You can map your custom objects starting from MBSection automatically using **`MBurgerMapper`** class. {% endhint %} Using the commodity class **`MBFieldsMapping`** which fields of your custom class should be mapped with the fields of the MBSection you named on your Project dashboard. Your destination object should at least override getters and setters and if you wish to obtain simple values or MBurger object values for: * Images -> First **`MBImage`** (only an object, not an array) * Media & Documents -> First **`MBFile`** (only an object, not an array) * Addresses -> Latitude, longitude or textual address You will find all possible simple data inside the **`MBMappingArgs`** class. {% hint style="info" %} Make sure your custom class is public and that provides getters and setters for all fields you wish to map. {% endhint %} For example, for a simple **`News`** class with title and MBurger image ```java class News: Serializable { var title: String? var img: MBImage? } ``` Can be mapped this way: ```kotlin val fieldsMapping = MBFieldsMapping() //”ttl” is my custom object element, “Title” is the name of the Element we want to map from the section fieldsMapping.putMap(“ttl”, “Title”) //”img” is my custom object element, “Images” is the name of the Element we want to map from the section, we add “imageArguments” which tells to take only the first image from the array. val imageArguments = arrayOf(MBMappingArgs.mapping_first_image_media) fieldsMapping.putMap(“img”, “Images”, imageArguments) //If getSimpleValues was “true” we would not have a single MBImage but the basic value, so the URL of the image and News class “img” should be a String val getSimpleValues = false; val nws = MBurgerMapper.mapToCustomObject(nkSection, fieldsMapping, News(), getSimpleValues) as News ``` {% hint style="info" %} If you need to map images, the SDK will return a MBImages object, which contains an array of MBImage. If you want an array of URLs you will have to set getSimpleValues to true. {% endhint %} {% hint style="warning" %} Due to the new nature of Android 9 this functionaity could give you light greylist logcat messages because it uses reflections. For now on, there should be no problem, but this functionality may change with new Android releases. {% endhint %} # Admin If you are also using editing and creating features (“ADMIN” features) within your app, you would also need to check **`MBurgerAdminTasks`**. {% hint style="info" %} All the concepts from the “client” usage are still valid, so all **`MBurgerAdminTasks`** methods have the “action” and the “listener” approach {% endhint %} {% content-ref url="/pages/-MDKW7yRz4SDCWtm1vlE" %} [Delete a Section/Media](/android-docs/admin-feature/delete-a-section-media) {% endcontent-ref %} {% content-ref url="/pages/-MDKW7ojmwXowxvKGp\_a" %} [Create a new Section](/android-docs/admin-feature/create-a-new-section) {% endcontent-ref %} {% content-ref url="/pages/-MDKW7afFY7W63t69LND" %} [Update an existing Section](/android-docs/admin-feature/update-an-existing-section) {% endcontent-ref %} # Delete a Section/Media In order to delete a specific section you will need to obtain the id from the MBSection objects you will retrieve through APIs. Then you will just have to call the static method ```java MBurgerAdminTasks.deleteSection(this, section_id); ``` which will return back the section\_id, with the listener **`MBAdminApiDeleteSectionListener`** and from the callback bundle in “action” mode using the **`MBApiPayloadKeys.key_section_id`**. Deleting a media from a section is pretty similar: ```java MBurgerAdminTasks.deleteMedia(this, media_id); ``` where **`media_id`** is the id of the media element you wish to delete, it can be used with both files and images. This method will return back the media\_id, with the listener **`MBAdminApiDeleteMediaListener`**, and from the callback bundle in “action” mode using the **`MBApiPayloadKeys.key_media_id`**. It’s suggested to maintain the **`MBObjects`** (`MBImage` for example) instead of simple values in order to maintain the media\_id in a simpler way. # Create a new Section {% hint style="info" %} Before creating a new section please take note of the names of the elements the section is made of and the id of the block you need to add a new section. {% endhint %} To create a new section you will need to use the static method ```kotlin MBurgerAdminTasks.addSection(applicationContext, block_id, params, params_file, Locale.getDefault().getLanguage()); ``` Where **`params`** is an ArrayList of **`MBAdminParameter`** and `params_file` is an ArrayList of **`MBAdminParameterFile`**. You will also need to provide the **`Locale`** (in “it” like form) for multilanguage sake support. {% hint style="warning" %} If the locale you’ll provide is not supported the API will return an error. {% endhint %} {% hint style="info" %} For the address field you should just give the textual address, MBurger API will automatically retrieve latitude and longitude of the address. {% endhint %} For example, if your section is composed like: * `title` -> text field * `content` -> text field * `link` -> text field * `image` -> array of media (images) So your code for adding a new section (assuming the supported locale is the same as your device) will result like this: ```kotlin //EditTexts for inserting content val edt_title: EditText val edt_content: EditText val edt_link: EditText var listener: MBAdminApiAddSectionListener var block_id = //BLOCK_ID //URI of the image, taken from camera or gallery var img_uri: Uri fun addSection() { val params = ArrayList() params.add(MBAdminParameter(“title”, edt_title.getText().toString())) params.add(MBAdminParameter(“content”, edt_content.getText().toString())) params.add(MBAdminParameter(“link”, edt_link.getText().toString())) val params_file = ArrayList() val files = ArrayList() files.add(MBAdminSingleFile(getFileName(), getMimeType(), getUriRealPath(application(), img_uri))); params_file.add(MBAdminParameterFile(“image”, files)); MBurgerAdminTasks.addSection(applicationContext, block_id, listener, params, params_file, Locale.getDefault().getLanguage()); } ``` {% hint style="info" %} Where **`getFileName()`**, **`getMimeType()`**, **`getUriRealPath(getApplication()`**, **`img_uri`**) are methods to obtain the image name, image mime type and the full file path from the image Uri you should implement on your own. {% endhint %} # Update an existing Section Updating a section is a process very similar to creating a new one, but you will need the id of the section you wish to update--the block\_id is not necessary. {% hint style="info" %} You should only pay attention in that you must provide a valid locale and only the section with the given locale will be updated; other locale variants will remain untouched. {% endhint %} Also, all media you will send through the API will be appended to the pre-existent array of media. If you wish to replace and image or a media you will need to call the **`MBurgerAdminTasks.deleteMedia(this, media_id)`** method before calling the update. If you wish to update a section, the method is similar to creating one: ```kotlin //EditTexts for inserting content val edt_title: EditText val edt_content: EditText val edt_link: EditText var listener: MBAdminApiUpdateSectionListener val section_id = //ID of the section you wish to update //URI of the image, taken from camera or gallery var img_uri: Uri //Set if you want this section to be hidden when requesting for block sections, or not val show_in_app = true; fun updateSection() { val params = ArrayList() params.add(MBAdminParameter(“title”, edt_title.getText().toString())) params.add(MBAdminParameter(“content”, edt_content.getText().toString())) params.add(MBAdminParameter(“link”, edt_link.getText().toString())) val params_file = ArrayList() val files = ArrayList() files.add(MBAdminSingleFile(getFileName(), getMimeType(), getUriRealPath(application, img_uri))) params_file.add(MBAdminParameterFile(“image”, files)) MBurgerAdminTasks.updateSection(applicationContext, section_id, listener, params, params_file, Locale.getDefault().getLanguage(), show_in_app); } ``` # Auth {% hint style="info" %} If your project is configured to register users you can use the **Auth** features of MBurger. {% endhint %} You will need to check the **`MBurgerAuthTasks`** class, where you will find all static methods to use authentication API, both with “action” and “listener” approach {% content-ref url="/pages/-MDKXqEiKNXvNmDEujqo" %} [Register a new user](/android-docs/auth-feature/register-a-new-user) {% endcontent-ref %} {% content-ref url="/pages/-MDKXqJoqufDc0bCxFay" %} [Authenticate a user](/android-docs/auth-feature/authenticate-a-user) {% endcontent-ref %} {% content-ref url="/pages/-MDKXqX6PAsyGM2GSe\_b" %} [User profile](/android-docs/auth-feature/user-profile) {% endcontent-ref %} {% content-ref url="/pages/-MDKXqeIrtUhDxxeJVJD" %} [Edit profile](/android-docs/auth-feature/edit-profile) {% endcontent-ref %} {% content-ref url="/pages/-MDKXpM1dmNEBDRWJMkX" %} [Other features](/android-docs/auth-feature/other-features) {% endcontent-ref %} # Register a new user If you wish to register a new user you will have to call the **`MBurgerAuthTasks.registerUser(…)`** method. {% hint style="warning" %} Be aware that a Nooko user contains these fields, some required, some not required, and some autofilled when registering. {% endhint %} * (Auto-filled) `ID` * (Required) `Name` * (Required) `Surname` * (Required) `Email` * `Phone` * `Image` * `Auxiliar data` * (Auto-filled) `Auth mode` Where Auxiliar data is an arbitrary string you can pass while registering a user. So registration code will result: ```kotlin private var listener: MBAuthApiRegisterListener private var edt_name, edt_surname, edt_email, edt_password: EditText private var phone: String private var img_uri: Uri private var auxiliar_data: String MBurgerAuthTasks.registerUser(applicationContext, listener, //Listener for registration edt_name.getText().toString(), //Name, REQUIRED edt_surname.getText().toString(), //Surname, REQUIRED phone, //Phone number, nullable img_uri, //Image, nullable edt_email.getText().toString(), //Email, REQUIRED edt_password.getText().toString(), //Password REQUIRED auxiliar_data); //Auxiliar data nullable ``` This method won’t return anything less than an error if the email is already taken or any other problem occurred. {% hint style="info" %} To obtain the profile of the user and also to call all the other API with this authorization, you will need to **login** this user. {% endhint %} # Authenticate a user After a successful registration you would probably need to authenticate your user by using the registration email and password, so you will need to call: ```kotlin private var listener: MBAuthApiAuthenticateListener private var email, password: String MBurgerAuthTasks.authenticateUser(applicationContext, listener, //Listener for authentication email, //Email of the user password); //Password of the user ``` This method will return the **`jwt_token`** that will automatically be used in all subsequent calls until the app is uninstalled or the user is logged out in order to authenticate all API calls. It will be automatically stored encrypted within your application, but if you need to save it for your purposes you can obtain it through the listener or with the “action” mode inside the returned bundle with the key `MBApiPayloadKeys.key_jwt_token`. If you wish to **logout** a user just callJava ```kotlin MBurgerAuthTasks.clearAuthToken(applicationContext); ``` {% hint style="warning" %} Make sure that your app UI will respond to the “logout” in a significative way. {% endhint %} # User profile When a user is authenticated you can see their data on the dashboard. You can also obtain the user profile calling the API ```java private var listener: MBAuthApiProfileListener MBurgerAuthTasks.getLoggedUserProfile(applicationContext, listener); ``` This API call will return the profile of the actual authenticated user in the form of a **`MBAuthUser`**, which represents a registered user inside your project, you will find all the information you set in registration, with the “**auxiliar\_data**” field as you sent through the Signup API . {% hint style="warning" %} If you call this method before a login you will receive an error because there is no user authenticated, so make sure a user is authenticated before calling this API (you can easily achieve this by calling **`MBCommonMethods.hasLoggedIn(applicationContext).`** {% endhint %} # Edit profile Editing a profile looks a bit like registration, so, with a logged user you’ll need to call: ```kotlin private var listener: MBAuthApiProfileUpdateListener private var edt_name, edt_surname, edt_email, edt_password: EditText private var phone: String private var img_uri: Uri private var auxiliar_data: String MBurgerAuthTasks.updateProfile(applicationContext, listener, //Listener for registration edt_name.getText().toString(), //Name, REQUIRED edt_surname.getText().toString(), //Surname, REQUIRED phone, //Phone number, nullable img_uri, //Image, nullable edt_email.getText().toString(), //Email, REQUIRED auxiliar_data); //Auxiliar data nullable ``` If you decide not to set a new image, so the **img\_uri** value is null, the logged user original image will remain the same. # Other features ## Password Recovery You can add a “password lost” feature by calling the API:Java ```kotlin val email = edt_email.getText().toString(); MBurgerAuthTasks.requestPasswordRecovery(applicationContext, new MBAuthApiForgotPasswordListener() { override fun onForgotPasswordRequested() { //TODO show an alert } override fun onForgotPasswordRequestedError(error: String) { //TODO show an error dialog } }, email); ``` This API will send an email to the user registered with the indicated email, and if the `email` is not present, it will return an error. ## Password Editing You can add a “edit password” feature in your app by calling the API: ```kotlin val old_password = edt_old_password.getText().toString(); val new_password = edt_new_password.getText().toString(); MBurgerAuthTasks.changePassword(getApplicationContext(), new MBAuthApiChangePasswordListener() { override fun onPasswordChanged() { //TODO show an alert } override fun onPasswordChangedError(error: String) { //TODO show an error dialog } }, old_password, new_password); ``` {% hint style="info" %} This API will work only with an user authenticated. {% endhint %} # Proguard Rules {% hint style="info" %} If you are using proguard to shrink and obfuscate your code, you must not obfuscate the custom classes you want to map using the SDK or it will result in empty objects of exceptions. {% endhint %} To achieve that, you should add these lines to your proguard configuration file, replacing **`your.package.classname`** with your class full package name. ```java –keep class your.package.classname –keepclassmembers class your.package.classname { *; } ``` You may also need to add these lines to your proguard file: ```java –dontwarn okhttp3.** –dontwarn okio.** –dontwarn javax.annotation.** –dontwarn org.conscrypt.** –keepnames class okhttp3.internal.publicsuffix.PublicSuffixDatabase ``` # Plugins {% hint style="success" %} You can add functionalities to MBurger with plugins: classes that conform to the **`MBPlugin`** protocol that extends the functionalities of MBurger. Below there's a list of MBurger plugins supported {% endhint %} Below there's a list of MBurger plugins supported. Be aware that plugins are now only available in developer mode. ## Messages {% embed url="" %} MBMessages is a plugin library for [MBurger](https://mburger.cloud/), lets you display in app messages and manage push notifications in your app. The minimum deployment target for the library is 4.2 (API 17). Using this library you can display the messages that you set up in the MBurger dashboard in your app. You can also setup and manage push notifications connected to your MBurger project. ## Audience {% embed url="" %} MBAudience is a plugin libary for [MBurger](https://mburger.cloud/), that lets you track user data and behavior inside your and to target messages only to specific users or groups of users. This plugin is often used with the [MBMessages](https://github.com/Mumble-SRL/MBMessages-Android) plugin to being able to send push and messages only to targeted users. ## Automation {% embed url="" %} `MBAutomationAndroid` is a plugin libary for [MBurger](https://mburger.cloud/), that lets you send automatic push notifications and in-app messages crated from the MBurger platform. It has as dependencies [MBMessagesAndroid](https://github.com/Mumble-SRL/MBMessages-Android) and [MBAudienceAndroid](https://github.com/Mumble-SRL/MBAudience-Android). With this library you can also track user events and views. Using `MBAutomationAndroid` you can setup triggers for in-app messages and push notifications, in the MBurger dashboard and the SDK will show the content automatically when triggers are satisfied. # Sample Apps {% hint style="success" %} Check out these sample apps to learn how to start a MBurger-based project or get inspiration for your own app {% endhint %} {% content-ref url="/pages/-MDK\_zhmNY3kWHlEdHfn" %} [MBurger Explorer](/android-docs/sample-apps/mburger-explorer) {% endcontent-ref %} {% content-ref url="/pages/-MDKbj3GihXOmESfI4X\_" %} [MBurger Radio](/android-docs/sample-apps/mburger-radio) {% endcontent-ref %} # MBurger Explorer At [this repository](https://gitlab.mumbleserver.it/Mazzo/Noko3Sample/tree/develop) you’ll find a comprehensive, full-force sample app, with: * Home page * Photo gallery * Custom WYSIWYG * Contact data * Points of interest * List of partners * News list with detail. This sample teaches the basics of how to use MBurger: * Install the SDK * Initialize the SDK * Fetch Blocks and Sections * Use Filters ## App Requirements * Android Studio 3.1 * Target Android version 27 * Min SDK Version 17 * INTERNET permission * ACCESS\_NETWORK\_STATE permission ## MBurger Usage and Tutorial MBurger is initialized in the **`App`** class with a demo API KEY. It’s essential to initialize Nooko at the start of the application or else you won’t be able to use the sdk API. This sample uses **`MBurgerTasks`** static methods to retrieve data from MBurger dashboard. This class has public static functions which will call asynchronously MBurger API. You have 2 ways to retrieve data from API: * Listener * Actions In this sample, we are using the actions approach. ![MBurgerExplorer1](https://docs.mumbleideas.it/mburger/android/images/MBurgerExplorer1.png)MBurgerExplorer2 # MBurger Radio At [this repository](https://gitlab.mumbleserver.it/Mazzo/Nooko3Radio) you’ll find a comprehensive, sample radio app connected with Radio Bruno, with: * Streaming Home page * Streaming notification control * Events page * Contact data * News list with detail. This sample teaches the basics of how to use MBurger: * Install the SDK * Initialize the SDK * Fetch Blocks and Sections * Use Filters ## App Requirements * Android Studio 3.1 * Target Android version 27 * Min SDK Version 17 * INTERNET permission * ACCESS\_NETWORK\_STATE permission * MEDIA\_CONTENT\_CONTROL permission ![MBurgerRadio1](https://docs.mumbleideas.it/mburger/android/images/MBurgerRadio1.png) ![MBurgerRadio2](https://docs.mumbleideas.it/mburger/android/images/MBurgerExplorer2.png) # MBurger Apps {% hint style="success" %} Many satisfied clients have already taken a bite of MBurger and had a taste! Here are some use cases: {% endhint %} ### Green Places ![](https://is5-ssl.mzstatic.com/image/thumb/Purple114/v4/cf/7e/ae/cf7eae06-1aeb-2fd7-56cf-24c906756550/AppIcon-0-1x_U007emarketing-0-0-GLES2_U002c0-512MB-sRGB-0-0-0-85-220-0-0-0-7.png/230x0w.jpg) An Android and iOS application which permits owners of legal light drugs shops to register and create their own online shop showcase. Then, casual users can see the shops’ data and see which products are sold. [![Get it on Google Play](https://developer.android.com/images/brand/en_generic_rgb_wo_45.png)](https://play.google.com/store/apps/details?id=com.greenplaces.app) ### Radio Bruno ![](https://is1-ssl.mzstatic.com/image/thumb/Purple114/v4/56/08/b1/5608b1c2-e486-1170-6add-04d5ac98a645/AppIcon-0-1x_U007emarketing-0-0-GLES2_U002c0-512MB-sRGB-0-0-0-85-220-0-0-0-7.jpeg/230x0w.jpg) An Android and iOS application which allows users to listen to a popular Italian radio station, with a newsfeed, event photo gallery, live local TV streaming, music charts, links to simple games and a real-time native poll feature. [![Get it on Google Play](https://developer.android.com/images/brand/en_generic_rgb_wo_45.png)](https://play.google.com/store/apps/details?id=com.mumble.radiobruno) # iOS SDK To initialize the SDK you have to create a token through the [dashboard](https://mburger.cloud/). Click on the settings icon on the top-right and create an API Key specifying the permissions. On your app before doing anything you must initialize the SDK with your API Key by using the `MBurger` class, also you should specify if you are using the development api or the standard API, be aware that different mode means different key, so a "development api key" would not work if you are using standard api. ```kotlin MBurger.initialize("", ); ``` `MBurger.initialize()` also may accept other parameters to control if you want MBurger SDK to cache your requests, you will find all information you need inside the [Javadoc](https://github.com/Mumble-SRL/MBurger/tree/master/Javadoc). Requesting anything from the SDK before initializing will result in an exception, so you shoud initialize on your `onCreate` starting Activity or on your custom `Application` class. ### Client usage Basically you can obtain and use all your project data using 3 classes with public static methods: `MBurgerTasks`, `MBurgerMapper` and `MBurgerApiActionInitializer`. All these classes are used to obtain and map your custom objects from MBurger objects. # Introduction Follow these detailed tutorials to acquire confidence with the whole MBurger system. {% hint style="success" %} You will learn all the basic features as well as advanced and optional features. {% endhint %} Remember to also check the complete documentation page [here](https://docs.mumbleideas.it/ios/ios-reference/index.html). # Installation ## Swift Package Manager With Xcode 11 you can start using [Swift Package Manager](https://swift.org/package-manager/) to add **MBurgerSwift** to your project. Follow those simple steps: * In Xcode go to File > Swift Packages > Add Package Dependency. * Enter `https://github.com/Mumble-SRL/MBurgerSwift.git` in the "Choose Package Repository" dialog and press Next. * Specify the version using rule "Up to Next Major" with "1.0.7" as its earliest version and press Next. * Xcode will try to resolving the version, after this, you can choose the `MBurgerSwift` library and add it to your app target. ## CocoaPods [CocoaPods](https://cocoapods.org/) is a dependency manager for iOS, which automates and simplifies the process of using 3rd-party libraries in your projects. You can install CocoaPods with the following command: ```java $ gem install cocoapods ``` To integrate the MBurger into your Xcode project using CocoaPods, specify it in your Podfile: ```java platform :ios, ‘11.0’ target ‘TargetName’ do pod ‘MBurgerSwift’ end ``` If you use Swift, remember to add **`use_frameworks!`** before the pod declaration. Then, run the following command: ``` $ pod install ``` CocoaPods is the preferred method when installing the library. ## Carthage [Carthage](https://github.com/Carthage/Carthage) is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. To integrate MBurgerSwift into your Xcode project using Carthage, specify it in your Cartfile: ``` github "Mumble-SRL/MBurgerSwift" ``` ## Manual installation To install the library manually drag and drop the folder `MBurgerSwift` to your project structure in XCode. {% hint style="warning" %} Note that **`MBurgerSwift`** has **`MBNetworkingSwift (1.0.4)`** as dependency, so you have to install also this library. {% endhint %} # Initialization To initialize the SDK you have to create a token through the [dashboard](https://mburger.cloud/). Click on the settings icon on the top-right and create an API Key specifying the permissions. Then, in your **`AppDelegate application:didFinishLaunchingWithOptions:`** initialize the MBManager of the SDK setting a token like this: ```swift import MBurger … func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool { MBManager.shared.apiToken = "YOUR_API_TOKEN" return true } ``` ## Usage You will use the **`MBClient`** class to make all the requests to the api to retrieve data from MBurger. All the api calls have a plural version and the singular counterpart. For example, you can retrieve the list of blocks of the project or you can retrieve a single block giving its id. # Fetch the project You can retrieve the information of the project like this: ```swift MBClient.getProject(success: { project in }, failure: { error in }) ``` # Fetch blocks You can retrieve the blocks of the project with the function **`getBlocksWithParameters:Success:Failure`** like this: ```swift MBClient.getBlocks(success: { (blocks, paginationInfo) in }, failure: { error in }) ``` The parameter named **`parameters`** is an optional array of objects that conforms to the **`MBParameter`** protocol that will be passed to the MBurger api as parameter. The majority of the parameters that can be passed to the apis are already implemented in the SDK and can be used after the initialization: * `MBSortParameter` * `MBPaginationParameter` * `MBFilterParameter` * `MBGeofenceParameter` {% hint style="info" %} If you want to pass another type of parameter you can use the MBGeneralParameter class that can be initialized with a key and a value that will be passed to the apis. {% endhint %} So if you want to include a pagination parameter you can do this: ``` let paginationParam = MBPaginationParameter(skip: 0, take: 10) MBClient.getBlocks(withParameters: [paginationParam], success: { (blocks, paginationInfo) in }, failure: { error in }) ``` There are two other versions of the **`getBlocksWithParameters:Success:Failure`**: one that takes an additional parameter **`includingSections`** (a boolean that indicates whether or not include, for each block, the sections), and another that takes **`includingSections`** and **`includeElements`** (a boolean value that does the same thing but for the elements of the sections). So, you could retrieve the information of all the blocks, all the sections of the blocks, and all the elements of the sections with this call: ```swift MBClient.getBlocks(withParameters: [paginationParam], includingSections: true, includeElements: true, success: { (blocks, paginationInfo) in }, failure: { error in }) ``` # Fetch sections You can retrieve all the sections with a block with the given id with the function **`getBlocksWithParameters:Success:Failure`** like this: ```swift MBClient.getSections(ofBlock: THE_BLOCK_ID, parameters: nil, success: { (sections, paginationInfo) in }, failure: { error in }) ``` The **`parameters`** value is an array of **`MBParameter`** objects as described in the previous section. For the blocks, there’s a version of this function that takes a bool **`includeElements`** that indicates whether or not the elements of the section. If you want to retrieve all the sections of a block and their elements you can call: ```swift MBClient.getSections(ofBlock: THE_BLOCK_ID, parameters: nil, elements: true, success: { (sections, paginationInfo) in }, failure: { error in }) ``` # Media You can retrieve a media stored on MBurger with its id: ```swift MBClient.getMedia(withId: MEDIA_ID, success: { media in }, failure: { error in }) ``` To retrieve all the media that are saved in MBurger you can use this function: ```swift MBClient.getAllMedia(success: { media in }, failure: { error in }) ``` # Encoding & Decoding **`MBurgerSwift`** has a built in system that can be used to init your custom constructs. You have only to make your construct conform to **`MBDecodable`** protocol. For example a **`News`** that's reflecting a newsfeed block in MBurger: ```swift class News: MBDecodable { let text: String let images: [MBImage] let link: String let date: Date enum DecoderCodingKeys: String, CodingKey { case text case images case link case date } required init(from decoder: MBDecoder) throws { let container = try decoder.container(keyedBy: DecoderCodingKeys.self) text = try container.decode(String.self, forKey: .text) images = try container.decode([MBImage].self, forKey: .images) link = try container.decode(String.self, forKey: .link) date = try container.decode(Date.self, forKey: . date) } } ``` And call the **`decode`** function of **`MBDecoder`** to create and populate an array of news like this: ```swift MBClient.getSections(ofBlock: THE_BLOCK_ID, parameters: nil, elements: true, success: { (sections, _) in sections.forEach { section in do { if let elements = section.elements { let news = try MBDecoder.decode(News.self, elements: elements) newsArray.append(news) } } catch let error { self.showError(error) } } }, failure: { error in self.showError(error) }) ``` {% hint style="info" %} The DecoderCodingKey needs to match to the *`name`* of the element in the MBurger block(e.g. if the element on the dashboard is called *Title* the decoder key needs to be *Title*): {% endhint %} ```swift enum DecoderCodingKeys: String, CodingKey { case text = "Title" case images case link case date } ``` You can find a complete example in the Example project. # Serialization & Equality ## Serialization All the object models implement the **`Codable`** protocol so you can serialize and deserialize them without having to implement it. Below the list of objects that implement this protocol. * `MBProject` * `MBBlock` * `MBSection` * `MBElement` * `MBMedia` * `MBAddressElement` * `MBCheckboxElement` * `MBDateElement` * `MBDropdownElement` * `MBGeneralElement` * `MBImagesElement` * `MBMarkdownElement` * `MBMediaElement` * `MBRelationElement` * `MBPollElement` * `MBTextElement` * `MBColorElement` * `MBMultipleElement` * `MBUser` ## Equality All the model objects are conform to the **`Equatable`** protcol based on the corresponding id (e.g. an MBSection will result equal to another MBSection object if they have the same `sectionId`) # Admin If you need to create blocks and sections in your MBurger project you can use the [MBAdmin SDK](https://github.com/Mumble-SRL/MBAdmin) {% hint style="info" %} You will have to use a token with write permissions to edit the sections and with delete permissions to delete them. {% endhint %} ## Installation ### Swift Package Manager With Xcode 11 you can start using [Swift Package Manager](https://swift.org/package-manager/) to add **MBAdmin** to your project. Follow those simple steps: * In Xcode go to File > Swift Packages > Add Package Dependency. * Enter `https://github.com/Mumble-SRL/MBAdminSwift.git` in the "Choose Package Repository" dialog and press Next. * Specify the version using rule "Up to Next Major" with "1.0.6" as its earliest version and press Next. * Xcode will try to resolving the version, after this, you can choose the `MBAdminSwift` library and add it to your app target. ### CocoaPods [CocoaPods](https://cocoapods.org) is a dependency manager for Cocoa Projects, which automates and simplifies the process of using 3rd-party libraries in your projects. You can install CocoaPods with the following command: ```ruby $ gem install cocoapods ``` To integrate the MBurgerSwift into your Xcode project using CocoaPods, specify it in your Podfile: ```ruby platform :ios, '10.0' target 'TargetName' do pod 'MBAdminSwift' '~> 1.0.6' end ``` ### Chartage [Carthage](https://github.com/Carthage/Carthage) is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. To integrate MBAdmin into your Xcode project using Carthage, specify it in your Cartfile: ``` github "Mumble-SRL/MBAdminSwift" ``` ### Manual installation To install the library manually drag and drop the folder `MBAdminSwift` to your project structure in XCode. Note that `MBAdminSwift` has `MBurgerSwift` as a dependency, so you have to install also this library manually. # Add/Edit a section You can add a section to a block with the function **`addSectionToBlock(withBlockId:elements:success:failure:)`**. To call this function you need to create an array of elements confrom to **`MBUploadableElementProtocol`**. To create it use the **`MBUploadableElementsFactory`** that is created. A **`MBUploadableElementsFactory`** is allocated with a locale identifier and creates object with this locale identifier. {% hint style="info" %} All the integrity controls of the server are still present in the APIs, and you will find the description of the error in the object passed to the failure block. {% endhint %} Below is an example code to create a section. > Swift ```swift let factory = MBUploadableElementsFactory(localeIdentifier: "it") let elements: [MBUplodableElementProtocol] = [factory.createTextElement(name: "name", text: "text"), factory.createImageElement(name: "name", image: UIImage(named: "image_name")!)] MBAdmin.addSectionToBlock(withBlockId: BLOCCK_ID, elements: elements, success: { sectionId in }, failure: { error in }) ``` With a `MBUploadableElementsFactory` you can create: * an array or a single of image with `MBUploadableImagesElement` * an array or a single of image with `MBUploadableFilesElement` * a text with `MBUploadableTextElement` * a checkbox element with `MBUploadableCheckboxElement` The edit function is very similar to the add. {% hint style="info" %} It will modify only the fields passed and the other elements will remain untouched. {% endhint %} # Delete a section To delete a section with an id: ```swift MBAdmin.deleteSection(withSectionId: SECTION_ID, success: { }, failure: { error in }) ``` # Upload media You can upload media in 2 ways: * Uploading images, giving them names. In that case images will be converted in `jpg` (you can specify the compression quality). * Uploading files with their URL. To upload an image or multiple images: ```swift let image1: UIImage = AN_IMAGE let image2: UIImage = ANOTHER_IMAGE // Upload a single image MBAdmin.uploadMediaImage(image: image1, name: "Image name", success: { media in }, failure: { error in }) // Upload multiple images MBAdmin.uploadMediaImages(images: [image1, image2], names: ["Image1", "Image2"], success: { media in }, failure: { error in }) ``` To upload files with their URLs: ```swift let file1Url: URL = AN_URL let file2Url: URL = ANOTHER_URL // Upload a single file MBAdmin.uploadMedia(media: file1Url, success: { media in }, failure: { error in }) // Upload an array of files MBAdmin.uploadMedia(media: [file1Url, file2Url], success: { media in }, failure: { error in }) ``` # Delete a media {% hint style="info" %} You can delete a media (an image or a video), giving its id with the function. {% endhint %} The id of the media is the field id of the objects **`MBImage`** and **`MBFile`**. ```swift MBAdmin.deleteMedia(withMediaId: MEDIA_ID, success: { }, failure: { error in }) ``` # Auth {% hint style="success" %} All the authentication apis are contained in the **`MBAuth`** class. {% endhint %} You can register a user to MBurger, authenticate that user, and retrieve its information {% content-ref url="/pages/-MDKl-wtfW0yHPGOLkTO" %} [Register a user](/ios-docs/auth/register-a-user) {% endcontent-ref %} {% content-ref url="/pages/-MDKXqJoqufDc0bCxFay" %} [Authenticate a user](/android-docs/auth-feature/authenticate-a-user) {% endcontent-ref %} {% content-ref url="/pages/-MDKSY2DKOoxA7kF396E" %} [Retrieve user information](/ios-docs/auth/untitled) {% endcontent-ref %} {% content-ref url="/pages/-MDVJ1jWXda9Gi6pXioN" %} [Update user profile](/ios-docs/auth/update-user-profile) {% endcontent-ref %} ### ### # Register a user To register a user, call **`MBAuth.registerUser(withName:surname:…)`**. {% hint style="info" %} The fields, name , surname , email and password are required, while the other are optional. The field data is an arbitrary object (array or dictionary) representing additional data that you want to pass when registering the user. It will be returned when retrieving the profile. {% endhint %} ```swift MBAuth.registerUser(withName: "name", surname: "surname", email: "email", password: "password", phone: "1234567890", image: nil, data: nil, success: { }, failure: { error in }) ``` # Authenticate a user ## Email and password After registering the user, you can authenticate it with its email and password. {% hint style="info" %} All the communication with the server is made in https, so all the data is encrypted. If the authentication is correct, the api will return the access token. {% endhint %} This token will be put in the **`Authorization`** header for each subsequent call to all the MBurger apis. ```swift MBAuth.authenticateUser(withEmail: "email", password: "password", success: { accessToken in }, failure: { error in }) ``` ## Social MBurger offers the possibility to authenticate a user with social networks too. Socials currently supported: * Google * Facebook * Apple ```swift MBAuth.authenticateUser(withSocialToken: "socialToken", tokenType: Social_Token_Type, success: { accessToken in }, failure: { error in }) ``` {% hint style="info" %} If the user logs in with apple you need to pass to this function also the name and surname because those cannot be retrieved by the server {% endhint %} ## How to know if user is logged in You can see if a user is currently authenticated with **`MBAuth.userIsLoggedIn`**. If a user is authenticated you can retrieve its access token with **`MBAuth.authToken`** else this will return **`nil`**. To logout the current user: ```swift MBAuth.logoutCurrentUser({ }, failure: { error in }) ``` **`MBAuth`** saves the user information in the Keychain. {% hint style="info" %} If you are having issues when authenticating a user with the message “Couldn’t add the Keychain Item.” turn on Keychain sharing in your app capabilities section n for your app and add “com.mumble.mburger”. This should fix it. {% endhint %} ![Keychain settings](https://docs.mumbleideas.it/mburger/ios/images/Keychain.png) ### --- [Next Page](/llms-full.txt/1)