add documentation for requirejs support

djih · djih · commit 7d07b01456f9 · 2016-03-06T22:25:50.000-08:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,6 +3,7 @@
 * 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.
 
 ## 2.9.0 (January 15, 2016)
 
diff --git a/README.md b/README.md
@@ -7,21 +7,23 @@ Amplitude-Javascript
 1. If you haven't already, go to http://amplitude.com and register for an account. You will receive an API Key.
 2. On every page that uses analytics, paste the following Javascript code between the `<head>` and `</head>` tags:
 
-```
-<script type="text/javascript">
-  (function(e,t){var n=e.amplitude||{};var r=t.createElement("script");r.type="text/javascript";
-  r.async=true;r.src="https://d24n15hnbwhuhn.cloudfront.net/libs/amplitude-2.9.0-min.gz.js";
-  r.onload=function(){e.amplitude.runQueuedFunctions()};var s=t.getElementsByTagName("script")[0];
-  s.parentNode.insertBefore(r,s);var i=function(){this._q=[];return this};function a(e){
-  i.prototype[e]=function(){this._q.push([e].concat(Array.prototype.slice.call(arguments,0)));
-  return this}}var o=["add","append","clearAll","set","setOnce","unset"];for(var c=0;c<o.length;c++){
-  a(o[c])}n.Identify=i;n._q=[];function u(e){n[e]=function(){n._q.push([e].concat(Array.prototype.slice.call(arguments,0)));
-  }}var l=["init","logEvent","logRevenue","setUserId","setUserProperties","setOptOut","setVersionName","setDomain","setDeviceId","setGlobalUserProperties","identify","clearUserProperties"];
-  for(var p=0;p<l.length;p++){u(l[p])}e.amplitude=n})(window,document);
-
-  amplitude.init("YOUR_API_KEY_HERE");
-</script>
-```
+    ```html
+        <script type="text/javascript">
+          (function(e,t){var n=e.amplitude||{};var r=t.createElement("script");r.type="text/javascript";
+          r.async=true;r.src="https://d24n15hnbwhuhn.cloudfront.net/libs/amplitude-2.9.0-min.gz.js";
+          r.onload=function(){e.amplitude.runQueuedFunctions()};var s=t.getElementsByTagName("script")[0];
+          s.parentNode.insertBefore(r,s);var i=function(){this._q=[];return this};function a(e){
+          i.prototype[e]=function(){this._q.push([e].concat(Array.prototype.slice.call(arguments,0)));
+          return this}}var o=["add","append","clearAll","set","setOnce","unset"];for(var c=0;c<o.length;c++){
+          a(o[c])}n.Identify=i;n._q=[];function u(e){n[e]=function(){n._q.push([e].concat(Array.prototype.slice.call(arguments,0)));
+          }}var l=["init","logEvent","logRevenue","setUserId","setUserProperties","setOptOut","setVersionName","setDomain","setDeviceId","setGlobalUserProperties","identify","clearUserProperties"];
+          for(var p=0;p<l.length;p++){u(l[p])}e.amplitude=n})(window,document);
+
+          amplitude.init("YOUR_API_KEY_HERE");
+        </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:
@@ -261,6 +263,8 @@ 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*:
 
@@ -269,3 +273,40 @@ amplitude.init('YOUR_API_KEY_HERE', 'USER_ID_HERE', null, callback_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'.
+
+### 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/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/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.1-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>

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`