Amazon Mobile Analytics SDK for JavaScript
45 | Developer Preview: We welcome developer feedback on this project. You can reach us by creating an issue on the
46 | GitHub repository or posting to the Amazon Mobile Analytics forums:
47 | https://github.com/aws/aws-sdk-mobile-analytics-js
48 | https://forums.aws.amazon.com/forum.jspa?forumID=174
49 | Introduction
50 | The Mobile Analytics SDK for JavaScript allows JavaScript enabled applications to create and submit events for analysis in the AWS Console and through Auto Export to S3 and Redshift. The library uses the browser's local storage API to create a local cache for the data, allowing your web application to batch and record events even when the app is offline.
51 | Setup
52 |
53 | Download and include the AWS JavaScript SDK (minimum version 2.1.18):
54 |
57 | Download and include the Amazon Mobile Analytics SDK for JavaScript:
59 |
62 |
64 |
65 | <script src="/js/aws-sdk.min.js"></script>
66 | <script src="/js/aws-sdk-mobile-analytics.min.js"></script>
67 |
68 |
69 | Usage
70 | Step 1. Log in to the Amazon Mobile Analytics management console and create a new app. Be sure to note your App Id and Cognito Identity Pool Id.
71 | * https://console.aws.amazon.com/mobileanalytics/home/?region=us-east-1
72 | Step 2. Initialize the credentials provider using a Cognito Identity Pool ID. This is necessary for the AWS SDK to manage authentication to the Amazon Mobile Analytics REST API.
73 |
74 | AWS.config.region = 'us-east-1';
75 | AWS.config.credentials = new AWS.CognitoIdentityCredentials({
76 | IdentityPoolId: COGNITO_IDENTITY_POOL_ID //Required e.g. 'us-east-1:12345678-c1ab-4122-913b-22d16971337b'
77 | });
78 |
79 |
80 | Step 3. Instantiate the Mobile Analytics Manager, including your App ID generated in Step 1, above. Session events will be automatically recorded and the client will batch and automatically submit events to Amazon Mobile Analytics every 10 seconds.
81 |
82 | var options = {
83 | appId : MOBILE_ANALYTICS_APP_ID //Required e.g. 'c5d69c75a92646b8953126437d92c007'
84 | };
85 | mobileAnalyticsClient = new AMA.Manager(options);
86 |
87 |
88 | To manually force an event submission you can call:
89 |
90 | mobileAnalyticsClient.submitEvents();
91 |
92 |
93 | Additional Options
94 | Custom Events
95 | You can optionally add custom events to capture additional information you find valuable.
96 |
97 | mobileAnalyticsClient.recordEvent('CUSTOM EVENT NAME', {
98 | 'ATTRIBUTE_1_NAME': 'ATTRIBUTE_1_VALUE',
99 | 'ATTRIBUTE_2_NAME': 'ATTRIBUTE_2_VALUE'
100 | /* ... */
101 | }, {
102 | 'METRIC_1_NAME': 1,
103 | 'METRIC_2_NAME': 99.3
104 | /* ... */
105 | });
106 |
107 |
108 |
109 | Session Settings
110 | By default a session lasts 10 minutes. You can override this default setting when initializing the Mobile Analytics Manager by including "sessionLength" in the "options" object.
111 |
112 | var options = {
113 | appId : MOBILE_ANALYTICS_APP_ID,
114 | sessionLength: 300000 //Session Length in milliseconds. This will evaluate to 5min.
115 | };
116 | mobileAnalyticsClient = new AMA.Manager(options);
117 |
118 |
119 | A session's timeout can also be updated to allow for continuation of a session.
120 |
121 | //This will set the current session to expire in 5 seconds from now.
122 | mobileAnalyticsClient.resetSessionTimeout(5000);
123 |
124 | //This will reset the current session's expiration time using the time specified during initialization.
125 | //If the default setting was used (10 minutes) then the session will expire 10 minutes from now.
126 | mobileAnalyticsClient.resetSessionTimeout();
127 |
128 |
129 | Record Monetization Event
130 | You can record monetization events to enable reports such as Average Revenue Per User (ARPU) and more.
131 |
132 | mobileAnalyticsClient.recordMonetizationEvent(
133 | {
134 | productId : PRODUCT_ID, //Required e.g. 'My Example Product'
135 | price : PRICE, //Required e.g. 1.99
136 | quantity : QUANTITY, //Required e.g. 1
137 | currency : CURRENCY_CODE //Optional ISO currency code e.g. 'USD'
138 | },
139 | {/* Custom Attributes */},
140 | {/* Custom Metrics */}
141 | );
142 |
143 |
144 | Add App Details to Events
145 | Additional app and environment details can be added to the "options" object when initializing the SDK. These details will be captured and applied to all events and can be useful if using Auto Export for custom analysis of your data.
146 |
147 | var options = {
148 | appId : MOBILE_ANALYTICS_APP_ID, //Required e.g. 'c5d69c75a92646b8953126437d92c007'
149 | appTitle : APP_TITLE, //Optional e.g. 'Example App'
150 | appVersionName : APP_VERSION_NAME, //Optional e.g. '1.4.1'
151 | appVersionCode : APP_VERSION_CODE, //Optional e.g. '42'
152 | appPackageName : APP_PACKAGE_NAME, //Optional e.g. 'com.amazon.example'
153 | make : DEVICE_MAKE, //Optional e.g. 'Amazon'
154 | model : DEVICE_MODEL, //Optional e.g. 'KFTT'
155 | platform : DEVICE_PLATFORM, //Required valid values: 'Android', 'iPhoneOS', 'WindowsPhone', 'Blackberry', 'Windows', 'MacOS', 'Linux'
156 | platformVersion : DEVICE_PLATFORM_VER //Optional e.g. '4.4'
157 | };
158 | mobileAnalyticsClient = new AMA.Manager(options);
159 |
160 |
161 | Please note, if device details are not specified Amazon Mobile Analytics will make best efforts to determine these values based on the User-Agent header value. It is always better to specify these values during initialization if they are available.
162 | Further Documentation
163 | Further documentation and advanced configurations can be found here:
164 | https://aws.github.io/aws-sdk-mobile-analytics-js/doc/AMA.Manager.html
165 | Network Configuration
166 | The Amazon Mobile Analytics JavaScript SDK will make requests to the following endpoints
167 | For Event Submission: "https://mobileanalytics.us-east-1.amazonaws.com"
168 | For Cognito Authentication: "https://cognito-identity.us-east-1.amazonaws.com"
169 | * This endpoint may change based on which region your Identity Pool was created in.
170 | For most frameworks you can whitelist both domains by whitelisting all AWS endpoints with "*.amazonaws.com".
171 | Change Log
172 | v0.9.2:
173 | Bug Fixes:
174 | Fixed data loss issue on migration from previous versions
175 | v0.9.1:
176 | Updated Dependency: aws-sdk-js v2.2.37
177 | Increase base delay between retries from 30ms to 3s
178 | Allow passing of configurations to the low level client via clientOptions attribute
179 | Local events from different apps are stored in different locations
180 | Improved retry strategies
181 | CorrectClockSkew is enabled by default for Sigv4 Signatures per Issue#7
182 | Bug Fixes:
183 | Fixed timer from being killed in cases where multiple submissions happened in under a second
184 | Fixed duplicate batch re-submission to the Mobile Analytics service
185 | Fixed delayed auto-submission of first _session.start event
186 | * Fixed Safari throwing exception when in private browsing mode
187 | v0.9.0:
188 | * Initial release. Developer preview.
189 |