Atlas Messenger iOS

This repository contains the source code of Atlas Messenger, an example application built by Layer to showcase the capabilities of Atlas, a library of robust communications user interface components integrated with the Layer platform.

For Demo Purposes Only

You may be tempted to directly integrate Atlas Messenger code straight into your app as a shortcut, but this is not recommended. Developers that have tried to directly integrate Atlas Messenger code into existing apps without fully understanding how Layer concepts work end up frustrated and confused. Three important things to note about Atlas Messenger:

1. Atlas Messenger uses an Layer identity server and token provider designed to only be used with this project. You must use your own identity server and token provider when integrating Atlas into your application. For more information, check out our Authentication Guide.
2. Atlas Messenger has a cap of only 20 users.
3. The Layer identity server does not work with production app ids.

If you're interested in learning more about how Atlas works and how best to incorporate it into your application then please read the Atlas Documentation.

Getting Started

Building Atlas Messenger requires that you obtain a Layer App ID. You can obtain an App ID by registering for a Layer account on the Experience Atlas page. Alternately, a pre-built version is available for immediate testing at the same location.

Building Atlas Messenger

To build Atlas Messenger, you need a few a few standard iOS Development Tools:

1. Xcode - Apple's suite of iOS and OS X development tools. Available on the App Store.
2. CocoaPods - The dependency manager for Cocoa projects. CocoaPods is used to automate the build and configuration of Atlas Messenger. Available by executing $ sudo gem install cocoapods in your terminal.

Note: Make sure to use CocoaPods >= 1.0.0.

Cloning & Preparing the Project

Once you have installed the prerequisites, you can proceed with cloning and configuring the project by executing the following commands in your terminal:

$ git clone --recursive https://github.com/layerhq/Atlas-Messenger-iOS.git
$ cd Atlas-Messenger-iOS
$ rake init

These commands will clone Atlas Messenger from Github, configure the Atlas submodule in the Libraries sub-directory, and then install all library dependencies via CocoaPods. Once these steps have completed without error, you can open the workspace by executing:

$ open "Atlas Messenger.xcworkspace"

Using git submodules and development pods

You may wish to develop/debug Atlas in tandem with Atlas-Messenger-iOS. To do so, use the submodule variant of the rake init task:

rake init:submodules ui=1

Then, the Atlas source code will appear in the Xcode Project Navigator under Pods > Development Pods > Atlas.

Note:

To use the internal LayerKit repository as a development pod, provide the location to the local working copy like so:

rake init:submodules [ui=1] core=/path/to/.../LayerKit

/path/to/.../LayerKit must be a full canonical path, no relative or ~ paths.

Setting the App ID

Before running Atlas Messenger from source code you must configure the Layer App ID and Identity Provider URL. To do so, follow these steps:

App ID

Run rake configure:set_app_id["{YOUR_APP_ID}"] to set the App ID in 'LayerConfiguration.json', or set it manually by editing 'LayerConfiguration.json' directly.

Replace {YOUR_APP_ID} with your appID, obtained from the Atlas keys page.

Identity Provider URL

Run rake configure:set_identity_provider_url["{YOUR_IDENTITY_PROVIDER_URL}"] to set the Identity Provider URL in 'LayerConfiguration.json', or set it manually by editing 'LayerConfiguration.json' directly.

Replace {YOUR_IDENTITY_PROVIDER_URL} with your Identity Provider URL, obtained from the Instastart Identity Provider page.

Example

This is an example of what your LayerConfiguration.json file might look like. Notice that the root of the JSON file is an Array.

[
  { 
    "name": "Example App",
    "app_id": "layer://example/example",
    "provider_url": "https://www.yourproviderurl.com/example"
  }
]

You can now proceed with building and running Atlas Messenger. Select Run from the Product menu (or type ⌘R). After the build completes, Atlas Messenger will launch launch in your iOS Simulator.

Getting Oriented

Atlas Messenger was designed to strike a balance between being simple enough to quickly peruse the project, but full-featured enough to fully demonstrate the power of Atlas and Layer. As you begin working with the example code, keep the following things in mind:

• Layer is a hosted communications platform. All communications services leveraged by Atlas Messenger utilize the backend services hosted by Layer.
• LayerKit is the native iOS SDK for accessing the Layer communications platform. LayerKit handles the networking, persistence, security and synchronization necessary to implement robust native messaging. LayerKit also presents a programming model for accessing the Conversations and Messages that are transmitted through Layer.
• Atlas is a library of user interface components developed by Layer that provide fully integrated user interface experiences on top of LayerKit. Atlas has a direct dependency on LayerKit and is not usable standalone.

When working with the Atlas Messenger codebase you will encounter code coming from LayerKit (prefixed by LYR), Atlas (prefixed by ATL), and Atlas Messenger itself (prefixed by ATLM).

Navigating the Project

The project is organized as detailed in the table below:

Because Atlas Messenger is designed to showcase the capabilities of Atlas, most of the interesting code lives in Code/Controllers and Code/Views.

License

Atlas Messenger is licensed under the terms of the Apache License, version 2.0. Please see the LICENSE file for full details.

Contact

Atlas Messenger was developed in San Francisco by the Layer team. If you have any technical questions or concerns about this project feel free to reach out to Layer Support.

Credits

• Kevin Coleman
• Klemen Verdnik
• Blake Watters