# Welcome Welcome to Mitter.io Docs. This short guide will help you cruise around our documentation without breaking your head. This documentation is split into **3** broad categories for easy access: * **Platform Reference** - where you can learn more about the Mitter.io platform and the core concepts * **Getting Started** - where you can learn how to quickly whip up apps using Mitter.io for Android and the Web * **SDKs** - where you can explore our SDKs in depth and take full advantage of what they have to offer Head over to the [Get Mitter.io](/mitter.io-on-docker) page and get the platform running on your machine. > **When running the container** > > You will have to change the endpoint when using our SDKs to and endpoint serving the docker container. This depends on which ports you have exposed and how you are accessing your docker installation. Refer to the individual SDK documentation on how to override the default API endpoint. > > **If using the cloud sandbox** > > You can use the SDKs without changing the API URLs. They by default point to the cloud sandbox. If you’re new to Mitter.io, we would recommend you start by looking into the **Getting Started** section and get a hands-on idea of how Mitter.io works. After that, you can browse around the core platform concepts to learn more about the platforms and all the APIs that we expose for our service. Lastly, check out the SDKs section to see how you can leverage the platform features in your app without putting in too much effort writing boilerplate code. This flow should get you accustomed to Mitter.io and how it works. Nevertheless, feel free to browse around as you feel is best for you. Want a more detailed guide to the platform and how to build with it? Watch our webinars [here](https://www.youtube.com/watch?v=2EERT1O0CHQ)! We're excited to see what you build with Mitter.io! # Migrating from cloud to on-prem To migrate from a cloud mitter.io account to an on-prem solution, roughly the following steps need to be followed: 1. Host an instance of mitter on-prem using your deployment stack (in this walkthrough, we will use docker compose) 2. Make your instances reachable from the outside world 3. Migrate all the data from your cloud account to the on-prem account 4. Replace all endpoints that your services/apps were using to the new endpoints you have configured For getting a reachable endpoint, you'll most probably need a domain that points to wherever you have hosted mitter. A general overview of how mitter.io on docker works is provided on the [mitter.io on docker page](https://docs.mitter.io/mitter.io-on-docker). Do note that the image used on that page is not suitable for production deployments, as it bundles all services in a single container making replications and horizontal scaling that much difficult. ### Using docker-compose to host your mitter instance To get started, install docker compose from Following is a sample configuration of how you can host all mitter services from within docker compose: ``` version: '3.4' x-pgsql-common-variables: &pgsql-common-variables POSTGRES_USER: POSTGRES_PASSWORD: POSTGRES_DB: mitter-io-central PGSQL_HOST: PGSQL_PORT: 5432 x-rabbitmq-common-variables: &rabbitmq-common-variables RABBITMQ_DEFAULT_USER: RABBITMQ_DEFAULT_PASS: RABBITMQ_HOST: rabbit-mq RABBITMQ_PORT: 5672 x-minio-common-variables: &minio-common-variables MINIO_ACCESS_KEY: MINIO_SECRET_KEY: MINIO_MEDIA_STORE_BUCKET: equities-media services: rabbit-mq: image: rabbitmq:3.7.17-management restart: always logging: <<: *mitter-logging-config environment: <<: *rabbitmq-common-variables RABBITMQ_VM_MEMORY_HIGH_WATERMARK: 0.85 ports: - "15672" networks: - mitter-subnet redis: image: 'redis:4-alpine' command: 'redis-server --appendonly yes --appendfsync everysec --save "60 0"' restart: always ports: - "6379" volumes: - ./.data/redis-data:/data networks: - mitter-subnet minio: image: 'minio/minio:RELEASE.2019-08-07T01-59-21Z' command: 'server /data' restart: always ports: - "9000" environment: *minio-common-variables volumes: - ./.data/minio-data:/data networks: - mitter-subnet weaver: image: mitterio/weaver:dc-rc1-JU1120 restart: always labels: autoheal: "true" healthcheck: test: ["CMD", "wget", "-O", "-", "http://localhost:7180/health"] start_period: 40s timeout: 5s interval: 20s retries: 3 environment: <<: *pgsql-common-variables <<: *rabbitmq-common-variables WEAVER_ARGS: --config-file=/config/weaver.application.conf INIT_WAIT_TIME: 10 depends_on: - rabbit-mq ports: - "7180:7180" - "11951:11951" volumes: - ./config:/config - ./javaagent:/javaagent networks: - mitter-subnet mitter: image: mitterio/platform:dc-rc1-JU1120 restart: always logging: <<: *mitter-logging-config labels: autoheal: "true" healthcheck: test: ["CMD", "wget", "-O", "-", "http://localhost:11901/health"] start_period: 1m10s timeout: 5s interval: 20s retries: 3 depends_on: - weaver - redis - minio environment: <<: *pgsql-common-variables <<: *minio-common-variables CENTRAL_APPLICATION_CONFIG: | { "mitter.security.jwt.signing-key": "", "mitter.security.jwt.issuer": "", "mitter.central.cache.application-resolution.expireAfterCreate": "1", "mitter.central.cache.application-resolution.expireAfterUpdate": "1", "mitter.central.cache.application-resolution.expireAfterRead": "400", "mitter.central.cache.channel-resolution.expireAfterCreate": "1", "mitter.central.cache.channel-resolution.expireAfterUpdate": "1", "mitter.central.cache.channel-resolution.expireAfterRead": "400", "mitter.central.cache.user-resolution.expireAfterCreate": "1", "mitter.central.cache.user-resolution.expireAfterUpdate": "1", "mitter.central.cache.user-resolution.expireAfterRead": "400", "mitter.central.cache.counts.expireAfterCreate": "1", "mitter.central.cache.counts.expireAfterUpdate": "1", "mitter.central.cache.counts.expireAfterRead": "1", "mitter.services.internal.weaver.enabled": "true", "mitter.services.internal.weaver.internal-uri": "http://weaver:7181", "mitter.central.database-url": "postgres://$${POSTGRES_USER}:$${POSTGRES_PASSWORD}@$${PGSQL_HOST}:$${PGSQL_PORT}/$${POSTGRES_DB}", "mitter.plugins.directory": "/plugins", "mitter.media.store.minio.uri": "http://minio:9000", "mitter.security.token-issuance.redis-uri": "redis:6379:0", "mitter.security.contexts.user-jwt-cookie.enabled": "true", "spring.servlet.multipart.max-file-size": "6MB", "spring.servlet.multipart.max-request-size": "7000KB", "logging.level.io.mitter.commons.spring.RequestBeanManagement": "ERROR", "logging.level.io.mitter.security.manager.PrincipalManager": "ERROR", "logging.level.acl-execution": "WARN", "logging.level.io.mitter.auth.context": "WARN", "logging.level.io.mitter.auth.resolvers": "WARN", "logging.level.io.mitter.security.support.WebPrincipalResolutionState": "WARN", "logging.level.io.mitter.auth.filters.JwtProcessingFilter": "WARN", "mitter.central.skip-request-logging": "^OPTIONS:.*$$,^GET:.*/presence.*$$,^GET:.*/counts/.*$$,^GET:.*/users/me$$", "mitter.central.cors-allowed-origins": "*", "server.tomcat.max-threads": "400", "spring.datasource.hikari.maximumPoolSize": "10", "mitter.central.outflow": "false", "mitter.security.token-issuance.users.expiry-time": "2112912000", "mitter.security.token-issuance.users.maximum-tokens": "3000" } DASHBOARD_JVM_ARGS: | -Dmitter.security.auth.basic-auth.enabled=true -Dmitter.security.auth.basic-auth.username= -Dmitter.security.auth.basic-auth.password= -Dmitter.sui.base-uri=https://mitter-sui-nyc1-a0.equities.chat volumes: - ./plugins:/plugins - ./javaagent:/javaagent ports: - "11901:11901" - "11902:11902" - "11950:11950" networks: - mitter-subnet networks: mitter-subnet: ipam: driver: default config: - subnet: 172.24.0.0/22 ``` A few things to note in the configuration above: 1. The configuration is not expected to work by just copy-pasting the file as-is. It is there to give a reference for your implementation. 2. In the example above, it is assumed that you are hosting your postgres database separately. For servicing real-world loads, we would recommend using CloudSQL or AWS RDS or a similar managed postgres service. If you want to run your own db, a docker container similar to the following will work: 1. `docker run --name mitter-postgres-db -e POSTGRES_PASSWORD= -e POSTGRES_USER= -e POSTGRES_DB=mitter-io-central -p 35332:5432 -d postgres:9.6.6-alpine` 3. Make sure you edit the `username` and `password` values for all running services in the first 3 sections of the file. They are then referenced in the `CENTRAL_APPLICATION_CONFIG` section of the configuration. 4. If you wish to continue running the mitter container with the dashboard enabled, then you should ideally not expose the dashboard port (in this example `11902`) to the outside world or the public internet. We would strongly recommend using either using an ssh tunnel or similar proxy mechanisms to access the dashboard. In supernova installs, the dashboard runs without authentication (as you would've expected on your cloud hosted account). In case you wish to access it using a public address, then you can enable basic auth with a username/password that can be specified as on line no. 147 / 148 in the snippet above. 5. Please do review the mount point of the `/data` volume in this docker compose installation. All media/images etc. get stored on this location - you would need to ensure adequate capacity as per your needs. ### Making your instance reachable While this will greatly differ from installation to installation, a sample of how a machine running the docker compose shown above can use `nginx` to make these services accessible is as follows ``` server { client_max_body_size 10M; server_name mitter.your-host.com; location / { proxy_pass http://localhost:11901; } listen [::]:443 ssl; listen 443 ssl; # managed by Certbot ssl_certificate /etc/letsencrypt/live//fullchain.pem; # managed by Certbot ssl_certificate_key /etc/letsencrypt/live//privkey.pem; # managed by Certbot include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot } server { server_name mitter-dashboard.your-host.com; location / { proxy_pass http://localhost:11902; } listen [::]:443 ssl; listen 443 ssl; # managed by Certbot ssl_certificate /etc/letsencrypt/live//fullchain.pem; # managed by Certbot ssl_certificate_key /etc/letsencrypt/live//privkey.pem; # managed by Certbot include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot } server { server_name mitter-weaver.your-host.com; location / { proxy_pass http://localhost:7180; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_read_timeout 86400; } listen [::]:443 ssl; listen 443 ssl; # managed by Certbot ssl_certificate /etc/letsencrypt/live//fullchain.pem; # managed by Certbot ssl_certificate_key /etc/letsencrypt/live//privkey.pem; # managed by Certbot include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot } server { if ($host = mitter.your-host.com) { return 301 https://$host$request_uri; } # managed by Certbot if ($host = mitter-dashboard.your-host.com) { return 301 https://$host$request_uri; } # managed by Certbot if ($host = mitter-weaver.your-host.com) { return 301 https://$host$request_uri; } # managed by Certbot listen 80 default_server; listen [::]:80 default_server; server_name mitter-weaver.your-host.com mitter.your-host.com mitter-dashboard.your-host.com return 404; # managed by Certbot } ``` ### Migrating your data By now, you would have received your entire data from the cloud account on your email. If you haven't, please reach out to `support@mitter.io`. To get started on the data migration, you will need three things: 1. An installation of `psql` on the some machine that can reach your postgres instance. This `psql` cli must be compatible with Postgres 9.6. 2. The data backup from your cloud account 3. A pre and post import script, available here : Once you have the three things ready, let's start first by applying the pre-import script: ``` psql -U -h -p -d mitter-io-central -f mitter-pre-import.sql ``` Then, extract your data archive and import that: ``` tar -xvzf .sql.tar.gz psql -U -h -p -d mitter-io-central -f .sql ``` Then finally, apply the post-import script: ``` psql -U -h -p -d mitter-io-central mitter-post-import.sql ``` Your data has already been transformed to run with mitter supernova builds, and all of your application ids, application keys, settings, user ids, message ids are preserved. All of your existing apps and APIs will continue to work as long as the API endpoints are modified. However, any user login information will not be persisted, and all of your users will have to fetch new authentication tokens. This is due to the fact that user tokens are signed by mitter's private key during issue and that data can longer continue to function without us distributing mitter's private key itself. (This is the 'signing-key' part of the configuration specificed in the docker-compose file). ### Migrating your apps To migrate your apps, all you will need to do is: 1. Modify the endpoint to which your API calls were being made to (i.e. you will have to change it from `https://api.mitter.io` to `https://mitter.your-host.com` or a similar domain name you have chosen to host these services on) 2. Do note that you will have to use some form a web server or a load balancer to expose your docker containers to the public internet via a domain name. It is not recommended to directly expose your docker ports from your machines. 3. For apps, you will require all of your users to re-login and fetch new tokens. If they have registered any prior FCM delivery endpoints, they will continue to work without any changes from your side. 4. Depending on which SDK you are using, please refer to the SDKs individual page for instructions on how to specify a different endpoint ### Troubleshooting If any of the containers refuse to start, or they are not working as expected, you can check the logs to troubleshoot these errors. To get a list of containers running, you could run ``` docker ps -a ``` If you used a docker compose file similar to the one above, you'd be seeing container names that begin with `mitter_`. Against these containers you should also be able to see if the containers are in a healthy or an unhealthy state. To check the logs, you can simply use: ``` docker logs --follow ``` # Get mitter.io Mitter is also distributed as a docker container publicly available on docker hub. It contains all the features of the public sandbox hosted at [mitter.io](https://mitter.io/) with the following exceptions: 1. You cannot register for an account or have multiple accounts for your services. Mitter runs in a single tenant mode. You can still however create multiple applications and use them with the same guarantees on data isolation. 2. Certain features like temporary media storage, distributed message broker, event bus is either not available or not supported. 3. If you are using multiple docker containers behind a load balancer, websocket deliveries will work intermittently. This is because there is no exchange of messages and connections between the serving nodes. To be able to serve traffic from multiple nodes, refer to the section 'Configuring an external broker'. > **NOTE** The Mitter.io docker container is currently in public beta and is encouraged to be used for development and testing. If you wish to run this in production, reach out to us at . ### Getting the docker container Getting the docker container is simple: ``` docker pull mitterio/mitter:sa ``` The mitter docker containers do not support the `latest` tag as mitter is expected to be delivered in the following formats: 1. `sa` - (AVAILABLE) The standalone build which bundles the platform, dashboard and all dependent servies. 2. `sa-headless` - (COMING SOON) The standalone build which bundles the platform all the dependent services, but not the dashboard. 3. `headless` - (COMING SOON) The `headless` build which bundles only the platform. It does not come with the dashboard and/or any dependent services. ### Running the docker container To run the container, simply execute: ``` docker run -p11901:11901 -p11902:11902 mitterio/mitter:sa ``` The two commands that are exposed make the platform and the dashboard available to the host. If you are exposing ports other than the ones mentioned, you will have to specify to the running container how to externally reach the API server. This is required for certain features in the dashboard to work (specifically the user and channels dev panel). To do so: ``` docker run -eAPI_ENDPOINT='http://localhost:1234' -p1234:11901 -p80:11902 mitterio/mitter:sa ``` Do note that if you do not wish to use the dashboard or do not intend to use the user and channels dev panel, specifying the step above is optional. ### Accessing the dashboard Once the container is running, you can access the dashboard on whichever port you mapped to `11902` on the container. This might take a while. > **NOTE** Sometimes even when the dashboard is available, you might see an error page for a while. This is due to the API server not being ready as it takes longer than the dashboard to start up. Refresh the page after sometime if that is the case. On the dashboard you can continue to create applications, users, channels etc. as usual. ### Building apps with the docker container The same SDKs and APIs work with your docker container as with the cloud solution. All SDKs provide a way to override the API URL which you must now point to the endpoint serving your docker container (and mapped to docker container `11901`). For specific information on the above, consult the individual SDK documentation. ### Persistence The provided docker image contains the required `VOLUME` directives for data to be persisted across container runs. For instance, if you were to run a container: ``` docker run -p.... mitterio/mitter:sa ``` Assume the container id was `9ba5901f6b80`, create users, send messages etc. and then stop the container and restart it: ``` docker stop 9ba5901f6b80 docker start 9ba5901f6b80 ``` then all the data would be persisted between the two runs. However, the following data will be no longer available: 1. All user authorizations will no longer be available. 2. Any pending message deliveries on websockets will not be persisted and those delivery attempts will be marked as permanent failures on subsequent runs. We are working on remedies to both the solutions. However, user authorizations will never be completely guaranteed to be persisted between container runs as they are only periodically flushed to the disk. #### Backing up volumes If you wish to keep all data in a location at a convenient place rather than the docker volume storage, the following mountpoints need to be mapped: 1. `/data/supernova` - This contains all the data from PostgreSQL and Minio. 2. `/logs/supernova` - This contains all the logs generated by the API server, dashboard and the dependent services (Redis, PostgreSQL, Minio). # Custom configuration The Mitter.io docker container comes with some parameters that are configurable. In its current format the configurability is quite limited and we plan to add a lot more options very soon. ## Basic configuration When running the container the following environment variables can be provided: 1. `APP_AUTHORITY_NAME` - The name used to issue JWT tokens to users. On the cloud instance it is `mitter-io` 2. `API_ENDPOINT` - The publicly resolvable address for the API server. 3. `DASHBOARD_ENDPOINT` - The publicly resolvable address for the dashboard. This is not required to be modified unless you are extending the docker image and need some services to use the dashboard externally. ## Specifying an `APPLICATION_CONFIG` To further configure the running services, you can also supply an `APPLICATION_CONFIG` containing key-value pairs for various properties. The two environment variables used would be: 1. `CENTRAL_APPLICATION_CONFIG` - This passes an application configuration object to the API server. 2. `DASHBOARD_APPLICATION_CONFIG` - This passes an application configuration object to the dashboard. On the command line you would supply them using: ``` docker run -eCENTRAL_APPLICATION_CONFIG='{\ "mitter.property": "value"\ }' mitterio/mitter:sa ``` Since this can get quite lengthy to type and manage on the CLI (especially with the newlines), it is recommended to store the configuration in a file, let's say `mitter.api.config` and `mitter.dashboard.config` with the specific JSON and then supply it using: ``` docker run -eCENTRAL_APPLICATION_CONFIG=`cat mitter.api.config` \ -eDASHBOARD_APPLICATION_CONFIG=`cat mitter.dashboard.config` \ -p11901:11901 -p11902:11902 mitterio/mitter:sa ``` Do note that you cannot nest JSON properties, the entire property path must be specified as a single string in the `key`. You can, however use integer/boolean values when applicable. The supported properties are covered in the following sub-sections. ### Configuring the signing key for JWTs By default a random string is used for signing the JWTs for user authorization. This might not always be desired (although will always work if the JWTs are being verified by no other than your running container) and can be overridden using (along with other parameters for JWTs) the following in `CENTRAL_APPLICATION_CONFIG`: ``` { "mitter.security.jwt.issuer": ".. your issuer name ...", "mitter.security.jwt.validity": 1000, // Milliseconds "mitter.security.jwt.signing-key": ".. your key, base64 encoded .." } ``` ### Configuring an external broker To push messages via websockets from multiple docker containers behind a load balancer you will need to enable a rabbitmq server that can act as a central broker between the multiple containers. > **NOTE** This feature is currently experimental and not officially supported. A test container can be run simply using: ``` docker run rabbitmq ``` Refer to the rabbitmq documentation to find out the following information: 1. The port the RabbitMQ server is running on 2. The username and the password. Then enable the broker by adding the following in `CENTRAL_APPLICATION_CONFIG`: ``` { "mitter.delman.websockets.broker.enabled": true, "mitter.delman.websockets.broker.host": ".. host ..", "mitter.delman.websockets.broker.port": RABBITMQ_PORT, "mitter.delman.websockets.broker.username": ".. rabbitmq username ..", "mitter.delman.websockets.broker.password": ".. rabbitmq password .." } ``` ### Storing media in S3 If you do not wish to store media from messages (file messages, image messages etc.) locally where your container is running but instead on AWS S3 then you can configure the media storage to do so. > **NOTE** When images are stored in S3 there is no access protection mechanism active. You must designate a publically-accessible bucket that can be accessed by anyone. This is not recommended if you are handling sensitive data. > **NOTE** This feature is currently experimental and not officially supported. To configure the API server to store media in S3, set the following keys in your `CENTRAL_APPLICATION_CONFIG`: ``` { "mitter.media.store.minio.enabled": false, "mitter.media.store.s3.enabled": true, "mitter.media.store.s3.bucketname": ".. S3 bucket to store media in ..", "mitter.media.store.s3.aws.access-key": ".. aws access key ..", "mitter.media.store.s3.aws.access-secret": ".. aws secret key ..", "mitter.media.store.s3.aws.region": ".. aws region ..", } ``` ### Using an event bus You can also have the docker container send installation-wide events to an AWS SNS topic. The events sent on event bus are extremely granular and can result in a huge flux of messages to your message queue. Most use-cases can be solved by using a simpler and minimal Webhooks interface. > **NOTE** This feature is currently experimental and not officially supported. To configure an AWS SNS queue to receive all events on your installation, set the following keys in `CENTRAL_APPLICATION_CONFIG`: ``` { "mitter.eventing.entbus.enabled": true, "mitter.eventing.entbus.sns.topic-arn": ".. aws sns topic ..", "mitter.eventing.entbus.sns.aws.access-key": ".. aws access key ..", "mitter.eventing.entbus.sns.aws.access-secret": ".. aws secret key ..", "mitter.eventing.entbus.sns.aws.region": ".. aws region .." } ``` # Build Your First Android App Get started with Mitter.io by building a fully functional app that sends/receives messages in a group of users. > **NOTE** The Getting Started docs show you how to build your first Mitter.io app with our cloud-hosted sandbox only. > > To use it with your docker container, simply change the base API Url (when creating the mitter object) to the address of your running docker container. ## Introduction Before we get started with this tutorial, let’s have a quick primer on what Mitter.io is and what we will be building in this tutorial. ### What is Mitter.io? Mitter.io is a messaging platform that allows you to build apps around messaging. You can treat a message as something more than just an envelope for text with our platform. ### What are we going to build? In this tutorial, we’re going to build a simple chat app which allows private replies to specific participants in a group. ### Where's the repository for this project? You can find the complete project [**hosted on GitHub**](https://github.com/mitterio/mitter-android-demo). Feel free to clone the repository and play around. ### Tell me more! Want a detailed guide to building with the platform? Watch our webinars [here](https://www.youtube.com/watch?v=2EERT1O0CHQ)! # Setup We’ll get started by setting up the SDK first. ## Android The Mitter.io Android SDK is distributed freely via **jCenter** and you can add it easily to your project by adding it as a standard dependency. ### Creating a new project Create a new Android app project by following the standard procedure listed below. Alternatively, you can skip the setup part by cloning [**our starter template**](https://github.com/mitterio/mitter-android-starter) and loading it into Android Studio. To create a project from scratch, do the following: * Go to **File** * Click on **New**, followed by **New Project** * Follow the steps, keep everything set to default or customize to your needs ### Adding dependency Now add the Android SDK to your newly created project by opening up your `build.gradle` file and pasting the following line in the **dependencies** block: {% code title="build.gradle" %} ```groovy implementation 'io.mitter.android:core:0.1.7' ``` {% endcode %} Once that is added, perform a Gradle sync. ### Basic setup Now that you’ve added the SDK, the next step is to add some initial configuration for the SDK to work. > Note: This documentation contains code snippets for both Kotlin and Java. Switch to the relevant tab while building the demo. To start working, you need to configure a `Mitter` object with your application details, which you can access from the Mitter.io Dashboard. Before you proceed, visit the Mitter.io Dashboard, create an application and grab the application ID. Next, you need to create a custom implementation of the `Application` class for your app. You can do so by creating a new class and extending the `Application` class: {% tabs %} {% tab title="Kotlin" %} {% code title="MyApp.kt" %} ```kotlin class MyApp: Application() {} ``` {% endcode %} {% endtab %} {% tab title="Java" %} {% code title="MyApp.java" %} ```java class MyApp extends Application {} ``` {% endcode %} {% endtab %} {% endtabs %} Once that’s in place, override the `onCreate()` method. This is where you’ll be configuring the `Mitter` object. Your custom `Application` class should look something like this: {% tabs %} {% tab title="Kotlin" %} {% code title="MyApp.kt" %} ```kotlin class MyApp: Application() { //Defining the mitter object lateinit var mitter: Mitter override fun onCreate() { super.onCreate() } } ``` {% endcode %} {% endtab %} {% tab title="Java" %} {% code title="MyApp.java" %} ```java class MyApp extends Application { //Defining the mitter object private Mitter mitter; @Override public void onCreate() { super.onCreate(); } } ``` {% endcode %} {% endtab %} {% endtabs %} Just defining the `Mitter` object isn’t enough. You need to configure it with the application ID that you retrieved from the Mitter.io Dashboard. Here's how to do that: Just paste this inside your `onCreate()` method in the `MyApp` class: {% tabs %} {% tab title="Kotlin" %} {% code title="MyApp.kt" %} ```kotlin val mitterConfig = MitterConfig( applicationId = "your-application-id-here" ) mitter = Mitter( context = this, mitterConfig = mitterConfig ) ``` {% endcode %} {% endtab %} {% tab title="Java" %} {% code title="MyApp.java" %} ```java MitterConfig mitterConfig = new MitterConfig( "your-application-id-here", LoggingLevel.BASIC, null ); mitter = new Mitter( this, mitterConfig, new UserAuth("", "") ); ``` {% endcode %} {% endtab %} {% endtabs %} #### Using the SDK with containerised Mitter.io If you're using the Mitter.io docker container, then you need to *override* the default API endpoint in the SDK, as follows: {% tabs %} {% tab title="Kotlin" %} {% code title="MyApp.kt" %} ```kotlin val mitterConfig = MitterConfig( applicationId = "your-application-id-here", apiEndpoint = MitterApiEndpoint( "http://localhost:11901", "http://localhost:11901" ) ) ``` {% endcode %} {% endtab %} {% tab title="Java" %} {% code title="MyApp.java" %} ```java MitterConfig mitterConfig = new MitterConfig( "your-application-id-here", LoggingLevel.BASIC, new MitterApiEndpoint( "http://localhost:11901", "http://localhost:11901" ) ); ``` {% endcode %} {% endtab %} {% endtabs %} That’s all you need to do for the very basic configuration. It’s not ready to connect with the platform just yet, but we’ll get to that part in the later sections. ### Setup FCM Mitter.io works hand-in-hand with **Firebase Cloud Messaging** (FCM) to deliver messages in real-time to Android devices. To start receiving messages, you need to setup FCM in your Android app and make a couple of changes in your application in the Mitter.io Dashboard. First of all, you need to setup FCM in your Android project. The steps for this setup are beyond the scope of this tutorial, and since Google has done a pretty good job explaining the same, you can [check out their docs](https://firebase.google.com/docs/cloud-messaging/android/client) if you haven’t already added FCM to your project. After you’re through with that, the only thing that's left is to feed your FCM server key in your Mitter.io application inside the Dashboard. You can do that by following these steps: * Open the Mitter.io Dashboard and select your application from the list * Go to the **Properties** tab * Click on **New Property** -> **Google** -> **FCM** -> **FCM Property** * You’ll get a modal where you need to fill out your app’s instance ID, which can be easily retrieved from the [Google Cloud Console](https://cloud.google.com/resource-manager/docs/creating-managing-projects)​ * Also, you need to feed in your **FCM server key**, which can be accessed from your FCM admin panel * After you’re done feeding this data, click on **New FCM Configuration Property** Once you’ve completed these steps, you need to register a delivery endpoint for Mitter.io to deliver your messages. In your Android project, create a class called `MyFirebaseMessagingService` which extends `FirebaseMessagingService` and override the `onNewToken()` method. In the `onNewToken()` you need to get a reference to your `Mitter` object which you declared in your custom `Application` class. {% tabs %} {% tab title="Kotlin" %} {% code title="MyFirebaseMessagingService.kt" %} ```kotlin class MyFirebaseMessagingService: FirebaseMessagingService() { override fun onNewToken(token: String?) { val mitter = (application as MyApp).mitter } } ``` {% endcode %} {% endtab %} {% tab title="Java" %} {% code title="MyFirebaseMessagingService.java" %} ```java public class MyFirebaseMessagingServiceJava extends FirebaseMessagingService { @Override public void onNewToken(String token) { Mitter mitter = ((MyApp) getApplication()).mitter; } } ``` {% endcode %} {% endtab %} {% endtabs %} Now that you have a reference to the `Mitter` object, you need to register the token with Mitter.io. Just add the following piece of code in your `onNewToken()` method: {% tabs %} {% tab title="Kotlin" %} {% code title="MyFirebaseMessagingService.kt" %} ```kotlin token?.let { mitter.registerFcmToken( it, object : Mitter.OnValueAvailableCallback { override fun onValueAvailable(value: DeliveryEndpoint) { //Delivery endpoint registered } override fun onError(error: ApiError) { //Delivery endpoint failed to register, retry } } ) } ``` {% endcode %} {% endtab %} {% tab title="Java" %} {% code title="MyFirebaseMessagingService.java" %} ```java if (token != null) { mitter.registerFcmToken( token, new Mitter.OnValueAvailableCallback() { @Override public void onValueAvailable(DeliveryEndpoint deliveryEndpoint) { //Delivery endpoint registered } @Override public void onError(ApiError apiError) { //Delivery endpoint failed to register, retry } } ); } ``` {% endcode %} {% endtab %} {% endtabs %} Once that is done, the next step is to intercept any incoming push messages and pass them to the SDK for processing. Get started by overriding the `onMessageReceived()` method and adding this piece of code inside the method: {% tabs %} {% tab title="Kotlin" %} {% code title="MyFirebaseMessagingService.kt" %} ```kotlin if (remoteMessage.data.isNotEmpty()) { val mitter = (application as MyApp).mitter val messagingPipelinePayload = mitter.parseFcmMessage(remoteMessage.data) if (mitter.isMitterMessage(messagingPipelinePayload)) { mitter.processPushMessage(messagingPipelinePayload) } } ``` {% endcode %} {% endtab %} {% tab title="Java" %} {% code title="MyFirebaseMessagingService.java" %} ```java if (!remoteMessage.getData().isEmpty()) { Mitter mitter = ((MyApp) getApplication()).mitter; MessagingPipelinePayload messagingPipelinePayload = mitter.parseFcmMessage(remoteMessage.getData()); if (mitter.isMitterMessage(messagingPipelinePayload)) { mitter.processPushMessage(messagingPipelinePayload, null); } } ``` {% endcode %} {% endtab %} {% endtabs %} Okay, the SDK is all set to intercept incoming messages and process them. The only thing that’s left is to register a callback on the `Mitter` object to get notified when a new message arrives. Head back to your custom `Application` class and register a `OnPushMessageReceivedCallback` on the `Mitter` object that you had already created. {% tabs %} {% tab title="Kotlin" %} {% code title="MyApp.kt" %} ```kotlin mitter.registerOnPushMessageReceivedListener(object : Mitter.OnPushMessageReceivedCallback { override fun onChannelStreamData( channelId: String, streamId: String, streamData: ContextFreeMessage ) { //Called when there's some streaming data such as typing indicator } override fun onNewChannel(channel: Channel) { //Called when a new channel is created where the user is a participant } override fun onNewChannelTimelineEvent( channelId: String, timelineEvent: TimelineEvent ) { //Called when there's a new timeline event for a channel } override fun onNewMessage( channelId: String, message: Message ) { //Called when a new message has arrived for the user } override fun onNewMessageTimelineEvent( messageId: String, timelineEvent: TimelineEvent ) { //Called when there's a new timeline event for a message } override fun onParticipationChangedEvent( channelId: String, participantId: String, newStatus: ParticipationStatus, oldStatus: ParticipationStatus? ) { //Called when the user has joined a new channel or has been removed from one } }) ``` {% endcode %} {% endtab %} {% tab title="Java" %} {% code title="MyApp.java" %} ```java mitter.registerOnPushMessageReceivedListener(new Mitter.OnPushMessageReceivedCallback() { @Override public void onNewMessage( String channelId, Message message ) { //Called when a new message has arrived for the user } @Override public void onNewChannel(Channel channel) { //Called when a new channel is created where the user is a participant } @Override public void onNewMessageTimelineEvent( String messageId, TimelineEvent timelineEvent ) { //Called when there's a new timeline event for a message } @Override public void onNewChannelTimelineEvent( String channelId, TimelineEvent timelineEvent ) { //Called when there's a new timeline event for a channel } @Override public void onParticipationChangedEvent( String channelId, String participantId, ParticipationStatus participationStatus, ParticipationStatus participationStatus1 ) { //Called when the user has joined a new channel or has been removed from one } @Override public void onChannelStreamData( String channelId, String streamId, ContextFreeMessage contextFreeMessage ) { //Called when there's some streaming data such as typing indicator } }); ``` {% endcode %} {% endtab %} {% endtabs %} You’re now done with the basic setup. Let’s move on to set up a user to start interacting with the platform and send messages. # Authenticate a User Add some users to your app and authenticate via the SDK. Before we can authenticate a user from our app, we need to create one. You can create a user in either of these **2** ways: * Use the dev panel (the "Users" tab when you select an application) in the Mitter.io Dashboard * Make an API call from your backend server In this example, we’ll be creating a user from the Mitter.io Dashboard using the dev panel. ## Create users from the dashboard Head over to the Mitter.io Dashboard and do the following: * Select your application from the list * In the left sidebar, click on the **Users** icon, and then click on **New User** * Give a name for your user and create one Since we’ll be creating a group chat channel in the upcoming steps, go ahead and create **2** or **3** more users with different names. Now, select one of the users you’ve created and click on **Add Token**. This will create an access token for the user. Copy the access token and keep it handy. Follow the same process for creating a channel. Just choose the channel type as **Group Chat** and add all the users that you created in the previous step. Once your channel is created, you’ll see a channel ID. Copy it and keep it handy as well. ## Add a user to your app Go back to your Android project and navigate to your custom `Application` class. First, you need to define a `UserAuth` object with the user details you acquired in the previous step. {% tabs %} {% tab title="Kotlin" %} {% code title="MyApp.kt" %} ```kotlin val userAuth = UserAuth( userId = "8ed92f3c-0696-4513-a842-085e3cee589e", userAuthToken = "eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJtaXR0ZXItaW8iLCJ1c2VyVG9rZW5JZCI6ImJtRlI5bWNQaDhkQnJHaWIiLCJ1c2VydG9rZW4iOiJiM2dvY2ZhZ3ZyNWlrNHJkbXJlc29wNnNlcyJ9.dlE1QOYmUJpqoh1kORm3hEI3KbBM0v8kKZQnQQwXR6TZuFiCaDQrJMlp-2dgNP1CTYCPMFYoqGctRWQ5JyNiOQ" ) ``` {% endcode %} {% endtab %} {% tab title="Java" %} {% code title="MyApp.java" %} ```java UserAuth userAuth = new UserAuth( "8ed92f3c-0696-4513-a842-085e3cee589e", "eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJtaXR0ZXItaW8iLCJ1c2VyVG9rZW5JZCI6ImJtRlI5bWNQaDhkQnJHaWIiLCJ1c2VydG9rZW4iOiJiM2dvY2ZhZ3ZyNWlrNHJkbXJlc29wNnNlcyJ9.dlE1QOYmUJpqoh1kORm3hEI3KbBM0v8kKZQnQQwXR6TZuFiCaDQrJMlp-2dgNP1CTYCPMFYoqGctRWQ5JyNiOQ" ); ``` {% endcode %} {% endtab %} {% endtabs %} You can get the user ID from the list of users in the **Users** tab. Make sure that the ID and auth token both belong to the same user. Now, just pass this `UserAuth` object to your previously configured `Mitter` object inside the `onCreate()` method in your `MyApp` class, like this: {% tabs %} {% tab title="Kotlin" %} {% code title="MyApp.kt" %} ```kotlin mitter = Mitter( context = this, mitterConfig = mitterConfig, userAuth = userAuth ) ``` {% endcode %} {% endtab %} {% tab title="Java" %} {% code title="MyApp.java" %} ```java mitter = new Mitter( this, mitterConfig, userAuth ); ``` {% endcode %} {% endtab %} {% endtabs %} Your Android app is now fully configured to make calls to the Mitter.io Platform. Let’s test that out by fetching some basic information for the currently logged-in user. ## Fetch currently logged-in user details Head over to your `MainActivity` and get a reference to the `Mitter` object inside the `onCreate()` method. {% tabs %} {% tab title="Kotlin" %} {% code title="MainActivity.kt" %} ```kotlin class MainActivity : AppCompatActivity() { private lateinit var mitter: Mitter override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) mitter = (application as MyApp).mitter } } ``` {% endcode %} {% endtab %} {% tab title="Java" %} {% code title="MainActivity.java" %} ```java public class MainActivity extends AppCompatActivity { private Mitter mitter; @Override protected void onCreate(@Nullable Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); mitter = ((MyApp) getApplication()).mitter; } } ``` {% endcode %} {% endtab %} {% endtabs %} Now, before making any calls, you need to get access to the basic group objects: * `Users` * `Channels` * `Messaging` Inside your `onCreate()`, define **3** objects like this: {% tabs %} {% tab title="Kotlin" %} {% code title="MainActivity.kt" %} ```kotlin val users = mitter.Users() val channels = mitter.Channels() val messaging = mitter.Messaging() ``` {% endcode %} {% endtab %} {% tab title="Java" %} {% code title="MainActivity.java" %} ```java Mitter.Users users = mitter.new Users(); Mitter.Channels channels = mitter.new Channels(); Mitter.Messaging messaging = mitter.new Messaging(); ``` {% endcode %} {% endtab %} {% endtabs %} You’re now all set to make calls. Let’s test out our setup by making a call to fetch the currently logged-in user details. You need to call the `getCurrentUser()` method on the `Users` object that you defined just now. {% tabs %} {% tab title="Kotlin" %} {% code title="MainActivity.kt" %} ```kotlin users.getCurrentUser( onValueAvailableCallback = object : Mitter.OnValueAvailableCallback { override fun onError(apiError: ApiError) { Log.d("MSA", "Error while fetching user: $apiError") } override fun onValueAvailable(value: User) { Log.d("MSA", "User is: ${value.screenName.screenName}") } } ) ``` {% endcode %} {% endtab %} {% tab title="Java" %} {% code title="MainActivity.java" %} ```java users.getCurrentUser(new Mitter.OnValueAvailableCallback() { @Override public void onValueAvailable(User user) { Log.d("MSA", "User is: "+ user.getScreenName().getScreenName()); } @Override public void onError(ApiError apiError) { Log.d("MSA", "Error while fetching user: " + apiError); } }); ``` {% endcode %} {% endtab %} {% endtabs %} If you’ve set everything up correctly, you should see something similar to this in your app’s logs: ``` D/MSA: User is: Jason ``` # Start a Basic Chat Let’s take this tutorial even further by building a simple chat UI and using Mitter.io to send/receive messages. ## Build the basic layouts Before we start handling data, we need a UI to show the outgoing/incoming data. Get started by adding some layouts for your chat bubbles and the chat `RecyclerView`. To speed up this tutorial, just copy and paste the following pieces of code to your project. This is very basic Android stuff and we’ll not be diving deep into this part. {% code title="back\_blue\_rounded.xml" %} ```markup ``` {% endcode %} {% code title="back\_gray\_rounded.xml" %} ```markup ``` {% endcode %} {% code title="item\_message\_self.xml" %} ```markup ``` {% endcode %} {% code title="item\_message\_other.xml" %} ```markup ``` {% endcode %} So, you’ve added some basic layouts for rendering the chat bubbles. Now, let’s style the chat window. Open up your `activity_main.xml` layout file and add the following code: {% code title="activity\_main.xml" %} ```markup