The purpose of this post is to assist with the process of integrating AMS Android library and hopefully answer any possible questions you might have about it. It assumes that you have already gone through the setup instructions described in the README.MD file and added at least one application to your AMS Dashboard.
AMSLibrary.java is a Java class that allows your android application to communicate with AMS web service. Its purpose is to simplify the process of logging messages on a remote server for a developer by abstracting all required formatting and network communication, therefore, minimizing amount of code and error checking.
Step 1 is to add AMSLibrary.java to your project. There are two ways to do this. The first one is to simply add the .java file to your existing Android project. The second one is to create a JAR library and include it in your application. I will purposely not go into further details on how to accomplish this in my post because it is out of scope. However, if you do need further help with this step, feel free to reach out to us and we will gladly provide assistance.
Once the library is included in your project, you only need to piece of information to initialize it. First, you need to provide URL of the AMS web service. Assuming that you have gone through the initial setup, it should look something like this: http://your_domain/ams_location/AMS/webservice.
Secondly, you need to specify your application key. An AppKey is basically just a unique id that is generated when you create a new application in the AMS Dashboard. It enables the web service to correlate received messages with a particular application.
The next step is to create an activity that you want to log. Inside AMSLibrary there is AppActivity object which contains the following 4 properties: type ID, message, description and notes. Additionally, there are 4 types of messages that are currently supported: success, warning, error and info. Please note that the library doesn't enforce any rules on what kind of information you can send. Our goal is to enable developers to have as much flexibility as possible. However, for organizational purposes, we suggest that you use correct types for your messages. The rest of the properties are pretty self-explanatory and completely optional.
After you have created an activity object and populated it with information you want to send, the last thing you need to do is to call the logActivity function and pass your activity, and you are done! The AMSLibrary will send your data to AMS web service which will log it in your database. This makes your data instantly available via AMS Dashboard.
There are few important things that happen behind the scene. First of all, the communication between the library and the remote server is asynchronous which means that your application doesn't have to wait for the library to finish and can continue executing. This ensures that your application will never experience a performance hit even when a user is on a slow network connection or your remote server is unavailable for any reason. It is also important to mention that “out of a box” AMS setup doesn't support encryption. Which means that messages that are sent from your application to the server are transmitted in plain text. Our reasoning behind this decision is based on the fact that encryption adds overhead and is only needed when sending sensitive data. If, in fact, your application is logging sensitive information the amount of developing effort to switch to an encrypted protocol is minimal. Finally, the current version of AMSLibrary doesn't store any data locally. This has its advantages as well as drawbacks. The main benefit of not storing any data to a local hard drive is efficiency. However, if your user isn't on a network connection when the logActivity call is made, the data will be lost. Once again, we wanted to leave it up to developers how they choose to handle this situation.
Feel free to contact us if you have any questions about the AMS or its setup. As usual, we welcome any constructive feedback you might have.
No comments:
Post a Comment