Add tryIdentifyFromParams API to SDK. (#14)

* Add tryIdentifyFromParams API to SDK.

This function looks for an `oeid` parameter in the query string of the
page and, if found and appears to be a valid sha256 hash-length hex
string, automatically try identify("e:"+oeid)

Lives in lib/addons/try_identify, now along with gpt_events.

* Update README with docs on oeid

README.md

@@ -246,6 +246,35 @@ Note that you can call `installGPTEventListeners()` as many times as you like on
 
 A working example of both targeting and event witnessing is available in the demo pages.
 
+## Identifying visitors arriving from Email newsletters
+
+If you send Email newsletters that contain links to your website, then you may want to automatically _identify_ visitors that have clicked on any such links via their Email address. Website traffic which is originating from a subscriber click on a link in a newsletter is considered to be implicitly authenticated by the recipient of the Email, therefore serving as an excellent source of linking of online user identities.
+
+### Insert oeid into your Email newsletter template
+
+To enable automatic identification of visitors originating from your Email newsletter, you first need to include an **oeid** parameter in the query string of all links to your website in your Email newsletter template. The value of the **oeid** parameter should be set to the SHA256 hash of the lowercased Email address of the recipient. For example, if you are using [Braze](https://www.braze.com/) to send your newsletters, you can easily encode the SHA256 hash value of the recipient's Email address by setting the **oeid** parameter in the query string of any links to your website as follows:
+
+```
+oeid={{${email_address} | downcase | sha2}}
+```
+
+The above example uses various personalization tags as documented in [Braze's user guide](https://www.braze.com/docs/user_guide/personalization_and_dynamic_content/) to dynamically insert the required data into an **oeid** parameter, all of which should make up a _part_ of the destination URL in your template.
+
+### Call tryIdentifyFromParams SDK API
+
+On your website destination page, you can call a helper method provided by the SDK which will attempt to parse and validate any **oeid** parameters passed to the page via query string and, when found, automatically trigger a call to Optable's **identify** API. This is illustrated in the following code snippet:
+
+```html
+<!-- Optable SDK async load: -->
+<script async src="https://sandbox.customer.com/static/web/sdk.js"></script>
+<script>
+  optable.cmd.push(function () {
+    optable.instance = new optable.SDK({ host: "sandbox.customer.com", site: "my-site" });
+    optable.instance.tryIdentifyFromParams();
+  });
+</script>
+```
+
 ## Demo Pages
 
 The demo pages are working examples of both `identify` and `targeting` APIs, as well as an integration with the [Google Ad Manager 360](https://admanager.google.com/home/) ad server, enabling the targeting of ads served by GAM360 to audiences activated in the [Optable](https://optable.co/) sandbox.

browser/sdk.ts

@@ -1,7 +1,9 @@
-import SDK from "../lib/sdk";
-import "../lib/gpt/events";
 import Commands from "./commands";
 
+import SDK from "../lib/sdk";
+import "../lib/addons/gpt-events";
+import "../lib/addons/try-identify";
+
 type OptableGlobal = {
   cmd: Commands | Function[];
   SDK: SDK["constructor"];

demos/vanilla/identify.html

@@ -12,6 +12,8 @@
           site: "web-sdk-demo",
           insecure: JSON.parse("true"),
         });
+
+        optable.instance.tryIdentifyFromParams();
       });
     </script>
     <script async src="http://localhost:8081/sdk.js"></script>

demos/vanilla/identify.html.tpl

@@ -12,6 +12,8 @@
           site: "web-sdk-demo",
           insecure: JSON.parse("${SANDBOX_INSECURE}"),
         });
+
+        optable.instance.tryIdentifyFromParams();
       });
     </script>
     <script async src="${SDK_URI}"></script>

lib/addons/try-identify.ts

@@ -0,0 +1,19 @@
+import SDK from "../sdk";
+
+declare module "../sdk" {
+  export interface SDK {
+    tryIdentifyFromParams: () => void;
+  }
+}
+
+function maybeValidEID(eid: string): boolean {
+  return eid.match(/^[a-f0-9]{64}$/i) !== null;
+}
+
+SDK.prototype.tryIdentifyFromParams = function () {
+  const qstr = new URLSearchParams(window.location.search);
+  const eid = qstr.get("oeid");
+  if (maybeValidEID(eid || "")) {
+    this.identify(["e:" + eid]);
+  }
+};