NAME

XAO::DO::Web::IdentifyAgent - class for agent (i.e. browser) identification.

SYNOPSYS

 <%IdentifyAgent%>

DESCRIPTION

The 'IdentifyAgent' class is used for agent identification purposes. It relies on some site configuration values which are available in the form of a reference to a hash. An example of this hash with all possible parameters is presented below, it should be stored in the site configuration under '/identify_agent':

 cb_uri           => 'IdentifyAgent', #opt., default is '/IdentifyAgent'
 id_cookie        => 'id_agent',      #optional, default is 'agent_id'
 id_cookie_expire => 126230400,       #optional, default is 4y
 list_uri         => '/Browsers',     #optional, see below
 access_time_prop => 'latest_access', #required if 'list_uri' present
 list_expire      => 126230400,       #opt., default is 'id_cookie_expire'

When a given 'IdentifyAgent' object is instantiated, it first checks the clipboard to determine if there is an agent id present, indicating that the agent has already been identified in the current session. If so, the work here is done.

If the agent has not already been identified, it checks whether there is a cookie named as 'id_cookie' parameter value ('id_agent' in example). If there is, the value of this cookie is the agent ID and saves to the clipboard. Otherwise, cookie is set to a unique agent ID value. The expiration time is set to 'id_cookie_expire' value if it is present and to 4 years otherwise.

Once the agent cookie is retrieved or an unique agent ID is generated for setting a new agent cookie a call is made to an 'IdentifyAgent' method called 'save_agent_id()'. This method first checks if there is a 'list_uri' parameter. If 'list_uri' is present then the agent ID is saved to this list, using agent ID as the list's key unless an entry for the agent already exists in the list. Otherwise, nothing is saved. Whenever saving an agent to the list, the access time is also saved in the database. Saving the access time also happens every time the agent is identified by a cookie.

Agent object is stored to clipboard under 'object' name if there is a 'list_uri' parameter. Otherwise, agent object remains undefined and only agent ID is stored under 'name' name.

METHODS

There are two methods available only. First of them is overriden display method that displays nothing but identifies user agent. And last of them is save_agent_id. See description below.

display (%)

Method displays nothing :-) but identifies user agent

save_agent_id ($$)

Method saves agent ID to database if 'list_uri' parameter present. Returns agent object or undef. May be overriden if more sophisticated agent data storage is required.

EXPORTS

Nothing

AUTHOR

Copyright (c) 2003-2005 Andrew Maltsev

<am@ejelta.com> -- http://ejelta.com/xao/

Copyright (c) 2001,2002 XAO, Inc.

Ilya Lityuga <ilya@boksoft.com>, Marcos Alves <alves@xao.com>, Andrew Maltsev <am@xao.com>

SEE ALSO

Recommended reading:

XAO::Web, XAO::DO::Web::Page, XAO::FS,