Merge pull request #48 from amplitude/fix_requirejs_support

djih · djih · commit f67274512aa1 · 2016-02-17T15:55:10.000-08:00
Add instructions for proper integration with RequireJS
diff --git a/.gitignore b/.gitignore
@@ -2,4 +2,5 @@ node_modules
 components
 npm-debug.log
 build
-dist
+dist
+.DS_Store
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,8 @@
 * Fix bug where saveReferrer throws exception if sessionStorage is disabled.
 * Log messages with a try/catch to support IE 8.
 * Validate event properties during logEvent and initialization before sending request.
+* Add instructions for proper integration with RequireJS.
+* Init callback now passes the Amplitude instance as an argument to the callback function.
 
 ## 2.9.0 (January 15, 2016)
 
diff --git a/README.md b/README.md
@@ -25,6 +25,8 @@ Amplitude-Javascript
         </script>
     ```
 
+    Note: if you are using [RequireJS](http://requirejs.org/), follow these [alternate instructions](https://github.com/amplitude/Amplitude-Javascript#loading-with-requirejs) for Step 2.
+
 3. Replace `YOUR_API_KEY_HERE` with the API Key given to you.
 4. To track an event anywhere on the page, call:
 
@@ -344,11 +346,50 @@ var trackClickLinkA = function() {
 };
 ```
 
+In the case that `optOut` is true, then no event will be logged, but the callback will be called. In the case that `batchEvents` is true, if the batch requirements `eventUploadThreshold` and `eventUploadPeriodMillis` are not met when `logEvent` is called, then no request is sent, but the callback is still called. In these cases, the callback will be called with an input status of 0 and response 'No request sent'.
+
 ### Init Callbacks ###
-You can also pass a callback function to init, which will get called after the SDK finishes its asynchronous loading. *Note: no values are passed to the init callback function*:
+You can also pass a callback function to init, which will get called after the SDK finishes its asynchronous loading. *Note: the Amplitude instance is passed to the callback function as an argument*:
 
 ```javascript
-amplitude.getInstance().init('YOUR_API_KEY_HERE', 'USER_ID_HERE', null, callback_function);
+amplitude.getInstance().init('YOUR_API_KEY_HERE', 'USER_ID_HERE', null, function(instance) {
+  console.log(instance.options.deviceId);  // access the instance's deviceId after initialization
+});
 ```
 
-In the case that `optOut` is true, then no event will be logged, but the callback will be called. In the case that `batchEvents` is true, if the batch requirements `eventUploadThreshold` and `eventUploadPeriodMillis` are not met when `logEvent` is called, then no request is sent, but the callback is still called. In these cases, the callback will be called with an input status of 0 and response 'No request sent'.
+### Loading with RequireJS ###
+If you are using [RequireJS](http://requirejs.org/) to load your Javascript files, you can also use it to load the Amplitude Javascript SDK script directly instead of using our loading snippet. On every page that uses analytics, paste the following Javascript code between the `<head>` and `</head>` tags:
+
+```html
+  <script src='scripts/require.js'></script>  <!-- loading RequireJS -->
+  <script>
+    require(['https://d24n15hnbwhuhn.cloudfront.net/libs/amplitude-2.9.0-min.gz.js'], function(amplitude) {
+      amplitude.init('YOUR_API_KEY_HERE'); // replace YOUR_API_KEY_HERE with your Amplitude api key.
+      window.amplitude = amplitude;  // You can bind the amplitude object to window if you want to use it directly.
+      amplitude.logEvent('Clicked Link A');
+    });
+  </script>
+```
+
+You can also define the path in your RequireJS configuration like so:
+```html
+  <script src='scripts/require.js'></script>  <!-- loading RequireJS -->
+  <script>
+    requirejs.config({
+      paths: {
+        'amplitude': 'https://d24n15hnbwhuhn.cloudfront.net/libs/amplitude-2.9.0-min.gz'
+      }
+    });
+
+    require(['amplitude'], function(amplitude) {
+      amplitude.init('YOUR_API_KEY_HERE'); // replace YOUR_API_KEY_HERE with your Amplitude api key.
+      window.amplitude = amplitude;  // You can bind the amplitude object to window if you want to use it directly.
+      amplitude.logEvent('Clicked Link A');
+    });
+  </script>
+  <script>
+    require(['amplitude'], function(amplitude) {
+      amplitude.logEvent('Page loaded');
+    });
+  </script>
+```
diff --git a/amplitude.js b/amplitude.js
@@ -158,11 +158,11 @@ Amplitude.prototype.runQueuedFunctions = function () {
  *  Maintain mapping of old functions to new instance methods
  */
 Amplitude.prototype.init = function(apiKey, opt_userId, opt_config, callback) {
-  this.getInstance().init(apiKey, opt_userId, opt_config, function() {
+  this.getInstance().init(apiKey, opt_userId, opt_config, function(instance) {
     // make options such as deviceId available for callback functions
-    this.options = this.getInstance().options;
+    this.options = instance.options;
     if (callback && type(callback) === 'function') {
-      callback();
+      callback(instance);
     }
   }.bind(this));
 };
@@ -395,7 +395,7 @@ AmplitudeClient.prototype.init = function(apiKey, opt_userId, opt_config, callba
   }
 
   if (callback && type(callback) === 'function') {
-    callback();
+    callback(this);
   }
 };
 
diff --git a/amplitude.min.js b/amplitude.min.js
diff --git a/scripts/version.js b/scripts/version.js
@@ -10,7 +10,7 @@ var cwd = process.cwd();
 
 function replaceVersion(filepath) {
   var filename = path.join(cwd, filepath);
-  fs.writeFileSync(filename, fs.readFileSync(filename, 'utf-8').replace(previous, version));
+  fs.writeFileSync(filename, fs.readFileSync(filename, 'utf-8').split(previous).join(version));
   console.log('Updated ', filepath);
 }
 
diff --git a/src/amplitude-client.js b/src/amplitude-client.js
@@ -146,7 +146,7 @@ AmplitudeClient.prototype.init = function(apiKey, opt_userId, opt_config, callba
   }
 
   if (callback && type(callback) === 'function') {
-    callback();
+    callback(this);
   }
 };
 
diff --git a/src/amplitude.js b/src/amplitude.js
@@ -49,11 +49,11 @@ Amplitude.prototype.runQueuedFunctions = function () {
  *  Maintain mapping of old functions to new instance methods
  */
 Amplitude.prototype.init = function(apiKey, opt_userId, opt_config, callback) {
-  this.getInstance().init(apiKey, opt_userId, opt_config, function() {
+  this.getInstance().init(apiKey, opt_userId, opt_config, function(instance) {
     // make options such as deviceId available for callback functions
-    this.options = this.getInstance().options;
+    this.options = instance.options;
     if (callback && type(callback) === 'function') {
-      callback();
+      callback(instance);
     }
   }.bind(this));
 };
diff --git a/test/browser/amplitudejs-requirejs.html b/test/browser/amplitudejs-requirejs.html
@@ -0,0 +1,79 @@
+<html>
+<!--<script src="src/amplitude-snippet.js" type="text/javascript"></script>-->
+<script src='require.js' type='text/javascript'></script>
+<script>
+    requirejs.config({
+      paths: {
+        'amplitude': 'https://d24n15hnbwhuhn.cloudfront.net/libs/amplitude-2.9.0-min.gz'
+      }
+    });
+
+    require(['amplitude'], function(amplitude) {
+      amplitude.init('a2dbce0e18dfe5f8e74493843ff5c053', null, {includeReferrer: true}, function() {
+        alert(amplitude.options.deviceId);
+      });
+
+      window.amplitude = amplitude;
+    });
+
+    var setUserId = function() {
+        var userId = prompt('Input userId', 'user01');
+        amplitude.setUserId(userId);
+    };
+    var setEventUploadThreshold = function() {
+        var eventUploadThreshold = parseInt(prompt('Input eventUploadThreshold', 5));
+        amplitude.options.eventUploadThreshold = eventUploadThreshold;
+    };
+    var logEvent = function() {
+        var event = prompt('Input event type', 'clicked');
+        amplitude.logEvent(event);
+    };
+    var setCity = function() {
+        var city = prompt('Input city', 'San Francisco, CA');
+        amplitude.setUserProperties({city: city});
+    };
+    var addToPhotoCount = function() {
+        var photoCount = parseInt(prompt('Input amount to increment photo count by', '2'), 10);
+        amplitude.identify(new amplitude.Identify().add('photoCount', photoCount));
+    };
+    var clickOnLinkA = function() {
+        amplitude.logEvent('Clicked on link A', null, function() { window.location='https://www.google.com'; });
+    };
+    var setPhotoCount = function() {
+        var photoCount = parseInt(prompt('Input photo count to set', '2'), 10);
+        amplitude.identify(new amplitude.Identify().set('photoCount', photoCount));
+    };
+    var setOncePhotoCount = function() {
+        var photoCount = parseInt(prompt('Input photo count to setOnce', '2'), 10);
+        amplitude.identify(new amplitude.Identify().setOnce('photoCount', photoCount));
+    };
+</script>
+<script>
+  require(['amplitude'], function(amplitude) {
+    amplitude.logEvent('Page loaded');
+  });
+</script>
+
+<body>
+<h3>Amplitude JS Test with RequireJS</h3>
+<ul>
+    <li><a href="javascript:setUserId();">Set user ID</a></li>
+    <li><a href="javascript:amplitude.setOptOut(!amplitude.options.optOut);">Toggle opt out</a></li>
+    <li><a href="javascript:logEvent();">Log event</a></li>
+    <li><a href="javascript:amplitude.logEvent('clicked button', {color: 'red;', shape: 'triangle', sides: 3});">Log
+        event with event properties</a></li>
+    <li><a href="javascript:amplitude.setUserProperties({age: 30, city: 'San Francisco, CA'});">Set user properties</a></li>
+    <li><a href="javascript:amplitude.options.batchEvents = !amplitude.options.batchEvents;">Toggle batch events</a></li>
+    <li><a href="javascript:setEventUploadThreshold();">Set event upload threshold</a></li>
+    <li><a href="javascript:clickOnLinkA();">Click on link A</a></li>
+    <br><br>Testing Identify calls<br>
+    <li><a href="javascript:addToPhotoCount();">Add to photo count</a></li>
+    <li><a href="javascript:amplitude.identify(new amplitude.Identify().unset('photoCount'));">Unset photo count</a></li>
+    <li><a href="javascript:setPhotoCount();">Set photo count</a></li>
+    <li><a href="javascript:setOncePhotoCount();">Set photo count once</a></li>
+    <li><a href="javascript:setCity();">Set city via setUserProperties</a></li>
+    <li><a href="javascript:amplitude.clearUserProperties();">Clear all user properties</a></li>
+    <br><br>
+    <li><a href="/test/browser/amplitudejs2.html">Go to second page</a></li>
+</body>
+</html>
diff --git a/test/browser/require.js b/test/browser/require.js

Original file line number	Diff line number	Diff line change
`@@ -10,7 +10,7 @@ var cwd = process.cwd();`
`10`	`10`
`11`	`11`	`function replaceVersion(filepath) {`
`12`	`12`	`var filename = path.join(cwd, filepath);`
`13`		`- fs.writeFileSync(filename, fs.readFileSync(filename, 'utf-8').replace(previous, version));`
	`13`	`+ fs.writeFileSync(filename, fs.readFileSync(filename, 'utf-8').split(previous).join(version));`
`14`	`14`	`console.log('Updated ', filepath);`
`15`	`15`	`}`
`16`	`16`
Original file line number	Diff line number	Diff line change
`@@ -146,7 +146,7 @@ AmplitudeClient.prototype.init = function(apiKey, opt_userId, opt_config, callba`
`146`	`146`	`}`
`147`	`147`
`148`	`148`	`if (callback && type(callback) === 'function') {`
`149`		`- callback();`
	`149`	`+ callback(this);`
`150`	`150`	`}`
`151`	`151`	`};`
`152`	`152`