What is the client ID when sending tracking data to google analytics via the measurement protocol?

I want to use Google's new measurement protocol for sending tracking events from my server instead of JavaScript.

This page says the client ID is required: https://developers.google.com/analytics/devguides/collection/protocol/v1/devguide#required

And this page says it's optional: https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#visitor

Plus, the format defined in these docs is different- the first page gives an integer as an example and just says it's "a unique value" while the second link says it should be a UUID.

If I send either user IDs or generated UUIDs on my backend, how will Google know to link that visitor to an existing visitor session? It seems like I would need to retrieve GA's internal reference to an existing user.

Any help is appreciated - thanks!

Integer or UUID

The cid is the equivalent of the second value in the _utma cookie when you use the javascript tracking. In js tracking, it is a random integer (generated by Math.round(2147483647 * Math.random())). But it is strored and sent as a string : so you can use both formats (integer or UUID).

Required/Optional

With js tracking, a request sent with a missing user id is ignored by Analytics servers. So assume that it is required.

Link web visitor with measurement protocol actions

If you want to link your backend user with a visitor previously tracked with Analytics javascript ga.js, you can get the cid value from the _utma cookie. But I don't recommend it; each time it changes (terminal or browser change, cookies cleaning, etc.), you will lose the link with your customer's previous actions.

Update

The analytics.js did not exist when the question was asked. cid is now stored in the cookie _ga. You can get it in javascript with:

ga(function(tracker) {
  var clientId = tracker.get('clientId');
});

As of writing this, when you do get the clientId from the tracker as in the above code it won't give you a UUID but two random 32-bit integers in the format of "X.Y". This implementation may change to the UUID in the future.

Or set it with your own value (like a backend generated UUID):

ga('create', 'UA-XXXXX-Y', {'clientId': 'your_client_id'});

In Rails:

  def save_google_analytics_client_id
    if current_user && cookies["_ga"]
      client_id = cookies["_ga"].split(".").last(2).join(".")
      if current_user.google_analytics_client_id != client_id
        current_user.google_analytics_client_id = client_id
        current_user.save
      end
    end
  end

I am using node with express and universal-analytics module and have chosen to use the cid embedded in the _ga cookie rather than generate my own cid server side.

my server.js looks like this...

app.use(function(req, res, next) {
  if(req.session && (!req.session.cid) && req.cookies._ga){
    //Use the cid already embedded in the _ga cookie and save to session so I can access from socket routes
    var gaSplit = req.cookies._ga.split('.');
    req.session.cid = gaSplit[2] + "." + gaSplit[3];
  };
  next();
});  

Then later on, I can do this..

ua = require('universal-analytics')
var visitor = ua('UAXXX', req.session.cid)

HTH