Git Product home page Git Product logo

amp-client-id-library's Introduction

NOTE: The library below is intended to be used in conjuction with the yet-to-be-released AMP Client ID API for custom integrations. Code and JavaScript libraries below aren't useful yet. If you want to use the AMP Client ID API in conjuction with Google Analytics, please consult the documentation for the AMP Client ID API in Google Analytics.

Google AMP Client ID Library

This Google AMP Client ID library provides a script that you can use to integrate the Google AMP Client ID API in your non-AMP pages for custom analytic systems (i.e., for in-house analytics tracking or for analytics vendors that are not preconfigured for use with the API. The Google AMP Client ID API provides you with the ability to consistently track users across AMP and non-AMP pages.

You can learn more about the API and how to customize your analytics systems in the Google AMP Client ID API documentation.

Usage

Choose one of the following options to integrate the Google AMP Client ID Library in your non-AMP pages:

Option 1: Use the compiled binary served on Google CDN (preferred)

  1. Add the following <script> tag in your HTML <head> section:

    <script async src="https://ampcid.google.com/client/v1.js"></script>
  2. In your JavaScript code, wait for the library load, then call the getScopedCid method:

    function ampCidApiOnload(callback) {
      (self.googleAmpCidApiOnload = self.googleAmpCidApiOnload || []).push(callback);
    }
    
    ampCidApiOnload(function(api) {
      api.getScopedCid('scope-abc', 'YOUR_API_KEY', function(err, cid) {
        if (err) {
          alert('Error: ' + err);
        } else {
          alert('Client ID:' + cid);
        }
      });
    });

Option 2: Copy the code into your own project

The recommended integration of the Google AMP Client ID library is to use binary that is served from CDN (option 1), which saves you from any future version updates. However, if you prefer not to load the extra binary, you can compile the code into your own project.

Specification

Methods

getScopedCid(scope, apiKey, callback): Returns the scoped client ID.

  • Parameters:
    • scope: The scope of the client ID, specified as a string. You can get different client IDs for the same user client by applying a different scope value. See Determine your AMP client ID scope for further information.
    • apiKey: The unique API key for the request, specified as a string. Apply for an API key via the Google AMP Client ID API in the Google API Console.
    • callback: A callback function that takes two parameters: function(err, cid).
      • err: An Error object if there is any error, otherwise null.
      • cid: The client ID string returned from the server.
  • Returns:
    • cid: A scoped client ID that can be one of the following:
      • A string starting with amp- followed by URL safe Base64 characters (for example, amp-UaFdEOQkTib3XGbPVGAJt0OQV8_1Hpmp8EsQOM5EySjmiK9UCs7yTCt219Fz2gER.
      • null, if the client ID was not found.
      • undefined, if an error occurred. An Error object is returned in this case.
      • '$OPT_OUT'. The client has opted out client ID tracking.

Cookie usage

The Google AMP Client ID library uses the AMP_TOKEN cookie to store information. This cookie serves two purposes:

  1. To persist a security token that is received from the API server, which can be used to exchange CID values next time.
  2. To act as a lock so that no concurrent requests are being sent.

Testing

To run tests on the Google AMP Client ID library, perform the following:

$ npm install
$ npm run test

amp-client-id-library's People

Contributors

cramforce avatar erwinmombay avatar lannka avatar rudygalfi avatar zhouyx avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.