CATERPILLAR APPS COMMUNITY (CAC) Analytics Integration Guide

Transcription

1 CATERPILLAR APPS COMMUNITY (CAC) Analytics Integration Guide

2 COPYRIGHT NOTICE This Documentation is the property of Caterpillar. All ideas and information contained in this document are the intellectual property of Caterpillar. This document is not for general distribution and is meant for use only by employees and people to whom it is distributed. This document will not be loaned to anyone, within or outside Caterpillar, without prior approval. Copying or unauthorized distribution of this document in any form or means, including electronic, mechanical, photocopying or otherwise, is illegal. Document No 1.0 Version. Rev 1.0 Authorized by Date Jun 09, 2015 Version History Version Release Date Comments 1.0 Jun 09,2015 Initial version 1 LAST UPDATED: 06/10/2015

3 Table of Contents 1. Introduction Intended Audience Steps to integrate App47 Analytics in mobile apps Analytics integration Prerequisites App47 Analytics integration on Android apps App47 Analytics Integration on ios apps Appendix Links for viewing Analytics Additional Analytics features: Help and Support LAST UPDATED: 06/10/2015

4 1. Introduction This document is intended to provide guidelines for integration of App47 Analytics in mobile apps for Android and IOS platform. DISCLAIMER: This document has been prepared using sample apps. 2. Intended Audience This technical document is targeted for Dealers, Partners and Sellers associated with Caterpillar and wishing to implement App47 Analytics in the apps distributed on Caterpillar Apps Community. 3. Steps to integrate App47 Analytics in mobile apps App47 EmbeddedAgent is integrated in mobile application to capture Analytics. Agent provides an easy to use API for recording session times and durations, log messages and performance events. Once the Mobile App has been added to the CAC Website Dashboard, the App ID generated will be used to configure the agent after installation. The App47 Analytics integration can be categorized based on app type: a. App47 Analytics integration on Android apps b. App47 Analytics Integration on ios apps Analytics integration Prerequisites Step 1: Membership in CAC Website: Implementing and viewing App47 analytics requires membership in CAC website. Dealers, Partners or Sellers wishing to implement App47 Analytics needs to contact CAC Admin to obtain membership and register on CAC Website. Links: 1. CAC QA Website 2. CAC Production Website Step 2: App ID generation in CAC Website Once member access is obtained, an AppID needs to be created on the CAC website for the mobile app. This AppID acts as a unique identifier for the app and will be set as a configuration parameter for the EmbeddedAgent. Registering to CAC QA Website offers the user full site access to the app including create, edit, view and delete options. However on the CAC Production website, the app creation and update will be monitored by CAC Admin and the member access will be limited to view only. 3 LAST UPDATED: 06/10/2015

5 3.2. App47 Analytics integration on Android apps. Step 1: Download App47 Analytics Embedded Agent zip file from the Resource center ( Note: Users need to login with the App47 membership credentials for accessing the resource center. Please contact Mobile support team (mobilesupport@cat.com) to be registered as member. Step 2: Include the Embedded Agent library into the app project i.e. copy the EmbeddedAgent.jar file to the directory in the project that contains libraries {PROJECT}/libs Fig 1.Adding android agent jar in libs folder Step 3: Add build dependency on EmbeddedAgent.jar. When using Eclipse, right click on the app s project folder -> Choose Build Path -> Add external archives ->.Choose EmbeddedAgent.jar from the file tree that appears -> Click Open once done. 4 LAST UPDATED: 06/10/2015

6 Fig 2.Add Build dependency Step 4: Add below lines of code for embedded Agent services and permission to AndroidManifest.xml Service declarations <service android:enabled="true" android:name="com.app47.embeddedagent.agentconfigservice"/> <service android:enabled="true" android:name="com.app47.embeddedagent.agentsessionservice /> <service android:enabled="true" android:name="com.app47.embeddedagent.agenteventservice"/> Permissions: <uses-permission android:name="android.permission.internet"/> <uses-permission android:name="android.permission.access_fine_location"/> 5 LAST UPDATED: 06/10/2015

7 Fig 3. Modify Manifest file Step 4: Add the code for onresume() and onpause() methods in the launcher activity class of the project and Register the Embedded agent as shown below : Fig 4.Register the Embedded Agent Step 5: Set the Embedded Agent configuration values: Using the method configureagentwithappid will record session start, duration, location and capture relevant device and app information. The App ID generated while creating the app in the CAC Website Dashboard is added as the second parameter in the configureagentwithappid method(). 6 LAST UPDATED: 06/10/2015

8 Fig5. Setting the configuration values CONFIGURATION VALUES EXPLAINED: Name Description Default Required Valid Values? Application id The App ID provided in your dashboard. None Yes Valid App ID from your account ConfigurationUpdateFr equency DelayDataUploadInterv al SendActualDeviceIdenti fier ConfigurationEndpoint The amount of time in days the agent should update it s configuration with the service. A value of 0.5 will cause the agent to update its configuration once every 12 hours. The number of seconds to wait after startup before sending data to the service. This allows your App to startup and be responsive without competing for valuable cpu and network resources. If the agent should send the actual UDID value from the device, or a hashed value. If this value is set to False, the value is hashed before being sent to the service, otherwise the actual value is sent. Configure where the agent will initially connect to retrieve configuration information and upload analytics 0.1 No Decimal number greater than zero, 1 = check once a day, 2= check every other day, 0.5 = check twice a day, =check every time. 10 No Integer value greater than zero. FALSE No True or false Yes QA - Production - Fig 6. Configuration values explained Step 6: Once the necessary API files have been added and the configuration values are set, the app can be started and the analytics details will be recorded by the EmbeddedAgent.The recorded details can be viewed in the CAC websites after logging in with membership credentials. 7 LAST UPDATED: 06/10/2015

9 3.3. App47 Analytics Integration on ios apps Step 1: Download App47 Analytics Embedded Compressed Disk image (DMG) file from the following link: Note: Users need to login with the App47 membership credentials for accessing the resource center Step 2: Create a dedicated folder in the project and copy the contents of the DMG file to the newly created folder. Then add the files to the project by right clicking on the project or a folder of your choosing. Fig 7. Adding required files from DMG. NOTE: The following details should be verified while adding the embedded agent files in the project code: File Check List There are several ways to include App47 into you ios app, please make sure that you have selected only one option in each group below. App47 Library Select one of the libembeddedagent libraries only, selecting more than one will cause compilation errors. libembeddedagent.a - Use this if you are going through itunes and want GEO data. libembeddedagentwithnocorelocation.a - Use this if you are going through itunes and do NOT want GEO data. Google Toolbox Library Include either the GoogleToolbox directory OR the libgmstacktrace.a file, but not both. 8 LAST UPDATED: 06/10/2015

10 If you have an ARC project and using the GoogleToolbox directory, make sure you exclude the files form the ARC compiler, please read this article on how to do exclude them. If you are using the libgmstacktrace.a file, please include the -all_load flag in the linker flag. Step 3: Add EmbeddedAgentSettings.plist file to set configuration parameters. The API endpoint values are as follows: Fig 8.Configure EmbeddedAgent plist file CONFIGURATION VALUES EXPLAINED: Name Type Description Default Require d? Application id String The App ID provided in your dashboard. Valid Values None Yes Valid App ID from your account ConfigurationUpd atefrequency DelayDataUploadI nterval show network activity Number Number Boolean The amount of time in days the agent should update it s configuration with the service. A value of 0.5 will cause the agent to update its configuration once every 12 hours. The number of seconds to wait after startup before sending data to the service. This allows your App to startup and be responsive without competing for valuable cpu and network resources. If the network indicator in the status bar should be turned on when sending data to the 0.1 No Decimal number greater than zero, 1 = check once a day, 2= check every other day, 0.5 = check twice a day, =check every time. 10 No Integer value greater than zero. YES No YES/NO 9 LAST UPDATED: 06/10/2015

11 ConfigurationEnd point String service. If this value is set to YES, the network activity indicator is turned on and off when sending data, otherwise the indicator is not updated when sending data. Configure where the agent will initially connect to retrieve configuration information and upload analytics Yes QA - Production - Step 4: Add the code for UncaughtException handler in the Application delegate file Fig 9. Unhandled Exception Handler Step 5 (Optional): If the application project is ARC enabled and using the GoogleToolBox directory, exclude the files in the directory by setting the compiler flag as shown below: Click the Project Build Phases Tab Compile sources Section Double Click on GoogleToolBox Add fno-obj-arc 10 LAST UPDATED: 06/10/2015

12 Fig10. Set Compiler flag for ARC projects Step 6: Once the necessary API files have been added and the configuration values are set, the app can be started and the analytics details will be recorded by the EmbeddedAgent.The recorded details can be viewed in the CAC websites after logging in with membership credentials. 4. Appendix 4.1 Links for viewing Analytics 1. QA Production Additional Analytics features: 1. Multiple logging levels: debug, info, warn, error and crash can be captured using App47 Analytics. Logs will be recorded locally and uploaded to the service next time the application resumes active state or is started. 2. Capturing Timed or Generic events 3. Adding Configuration groups 4. App auto upgrade 5. Listening to Agent Configured Event For details, refer: App47 Analytics for Android/ App47 Analytics for ios 4.3 Help and Support - CAC Admin 11 LAST UPDATED: 06/10/2015