pturbo
April 3rd, 2003, 09:36 AM
n-CASETM Client Integration
Written by:
Ken Smith (kens@180solutions.com)
Updated on April 3, 2003
Abstract
This paper provides a brief description of the n-CASE client, and outlines the requirements and alternatives for integrating the n-CASE client into your own application.
Table of Contents
n-CASETM Client Integration 1
INTRODUCTION 1
Components 1
Client 1
Identity Server 1
Profile Server 1
Control Interface 1
Terminology 1
Distributors 1
Subscribers 2
WHAT THE N-CASE CLIENT DOES 3
Description 3
Self-Registration 3
Ad Display 3
Data Collection 4
Automatic Update 4
HOW TO INTEGRATE THE N-CASE CLIENT 5
#1: Bundle the n-CASE Client With Your Setup 5
#2: Generate and Store a Unique Identifier 5
#3: Launch the n-CASE Client And Pass the Unique Identifier 6
INTRODUCTION
Components
The components of the 180Solutions n-CASE include the following:
Client
The n-CASE Client is a client-side Win32 application which serves as the primary communication point between the client and the n-CASE Identity Server as well as the primary data collection point. The n-CASE Client registers pseudonymous unique identifiers with the n-CASE Identity Server, collects and uploads click-stream, demographic and psychographic user data, and periodically displays advertisements and survey questions in compliance with the intent of P3P. The n-CASE client is described in more detail below.
Identity Server
The n-CASE Identity Server (n-CIS) is a server-side system which serves to pseudonymously and uniquely identify individuals, collect user data uploaded by the n-CASE Client, and aggregates demographic data to compile detailed predictive customer data.
Profile Server
The n-CASE Profile Server (n-CPS) redistributes predictive customer data (through various mechanisms) to Subscribers for use in pseudonymous analysis, pseudonymous decision, one-time tailoring or affirmative customization.
Control Interface
The n-CASE Control Interface (n-CCI) is a web-based interface which allows Subscribers to define their own demographics categories and pass-through HTML or XML templates.
Terminology
Distributors
Distributors are companies that have agreed to distribute the n-CASE client-side component. This component will be included in the distributor’s client-side applications, and will be used to pseudonymously and uniquely identify the user and to gather clickstream data. (See page 5 for a discussion of privacy issues.) Additionally, the demographics data that distributors collect from users will be collated and aggregated with the existing 180Solutions profile data. Each distributor is assigned a unique Distributor ID.
Subscribers
Subscribers are companies who use the n-CASE profile data to enhance users’ experience on their own web site: either through improved ad targeting, or through integration with their own personalization engines. Each Subscriber is assigned a unique Subscriber ID.
For More Inforation
For more information on n-CASE and the associated suite of technologies, see our white paper, posted at:
http://www.180solutions.com/n-case/n-case_whitepaper.doc
WHAT THE N-CASE CLIENT DOES
Description
The n-CASE client is a Win32 executable, and runs in a separate process from the Distributor’s application (as opposed to being implemented as a DLL or COM object). The primary reason for this is to make integration as easy as possible. Our goal was to require as few changes as possible – and in some instances, none whatsoever – to the Distributor’s application.
Self-Registration
The Distributor’s application will launch the n-CASE for the first time – either during setup, or later, after some sort of registration process has taken place. The n-CASE client typically takes a number of parameters, two of which are most important: “DID” (for Distributor ID), and “DUID” (for Distributor User ID). Each time the n-CASE client is launched with these two parameters, it takes the following actions:
(1) Writes the DID/DUID to the registry.
(2) Sets itself to run automatically on startup.
(3) Checks for an Internet connection, and as soon as one is available, contacts the n-CASE Configuration Server for configuration information.
(4) Posts the DID and DUID to the n-CASE Configuration Server.
(5) Receives a cookie from the n-CASE Configuration Server which is associated with that DID/DUID combination.
(6) Writes that cookie to the user’s browser(s).
It should be noted that if the n-CASE client is launched with a DID but not a DUID, it will contact the n-CASE Configuration Server to receive an automatically generated, random 30-character DUID.
Ad Display
One of the configuration details the n-CASE client receives from the configuration server is how often it should display a pop-up ad. This interval may range from once every 15 minutes to once every couple of days, and is set at the discretion of the Distributor. When that interval has passed, and the n-CASE client detects that an Internet connection is available, it displays a pop-up ad, targeted to that specific user.
Data Collection
While the user is connected to the Internet, the n-CASE client tracks clickstream data, and periodically uploads it to the n-CASE Identity Server. Before doing so, it checks to make sure that (a) an Internet connection is available, and (b) that it is not being highly utilized. When these conditions are met, it then performs its uploads in the background, batching the data before transmission, so that the user’s normal work is not affected.
Automatic Update
Once a day, the n-CASE client checks with the n-CASE Configuration Server to see if a new version is available. If there is, it downloads the new version, confirms a checksum on the downloaded file, replaces itself, launches the new version, and shuts itself down.
HOW TO INTEGRATE THE N-CASE CLIENT
To integrate the n-CASE client into your application, there are only three very simple things you need to do.
#1: Bundle the n-CASE Client With Your Setup
The n-CASE client must be installed in a directory other than that of your application. We recommend creating an “n-CASE” folder under “program files”. The application name is “msbb.exe”, and will be provided to you by 180Solutions. Also, your setup program must clearly message to users what n-CASE will do on their systems and give them the ability to terminate the installation. You may use opt-in or opt-out methods and you may require that users install n-CASE in order to install your application.
#2: Generate and Store a Unique Identifier
This step may not be required in some instances, but there are a number of benefits associated with it. If your contract requires sharing demographic information about your users with 180Solutions, it is a requirement.
This UID should not be anything that could personally identify the user, such as an email address or a user-chosen userid. The UID is limited to 30 characters and may include any ANSI character except “&”, “%”, and <space>.
If your application does not have the ability to communicate with a centralized server and thus choose a UID which is guaranteed unique throughout your namespace, and if you are not providing 180Solutions with demographic data, it is acceptable to have your application create a “statistically” unique UID, i.e., 30 random characters; or alternatively, by passing in a DID value but no DUID parameter. In this latter instance, the n-CASE client will request a randomly generated DUID from the n-CASE Configuration Server.
Once you have generated this UID, you should store it in the Windows Registry so that it may be permanently associated with this installation of your application.
#3: Launch the n-CASE Client And Pass the Unique Identifier
In most instances, your application should launch the n-CASE client as follows:
C:\MyAppDir\msbb.exe /did=DistributorID /duid=UniqueIdentifier
Your application only needs to successfully launch the n-CASE client once, preferably during your application’s installation process. For details about what the n-CASE client does once launched, see above.
And again, if you pass in a DID but no DUID, the n-CASE client will automatically request a randomly generated DUID from the n-CASE Configuration Server. However, this is not generally recommended, as it doesn’t allow for the sharing of specific demographic and usage information.
Note on CBC compliance:
If you wish to run in a fully CBC compliant mode, you must save the ncase.ini file to the user’s computer. Save this in the same folder as the n-CASE executable with the name “ncase.ini”. Your application should then launch n-CASE as follows:
C:\MyAppDir\msbb.exe /cbc=init /did=DistributorID /duid=UniqueIdentifier
This will prompt the user with the appropriate CBC wording. If you wish to edit the .INI file, please forward any changes for our review. Be aware that there is a limit to the size of this .ini file. The current file already meets that limit.
SHARING DEMOGRAPHICS INFORMATION
The deals that we negotiate with most Distributors require that they share with us whatever demographic data they collect about their customers. This is done by FTP-ing the demographics information for each day’s new users in comma-separated value (CSV) format to:
ftp://ftp.180solutions.com/demog/company_name/yyyymmdd.txt
Each text field in the file should be enclosed in double quotation marks (with any quotation marks within the text of the field double-quoted, i.e., “Toys-“”R””-Us”). Each record should be terminated with both a Carriage-Return and a Line-Feed character (chr(13) + chr(10)). (This is standard for Windows and similar systems, but must be specifically configured on Unix-based operating systems.)
Since the demographic information each distributor collects will be different, and the format for the information will vary from distributor to distributor, 180Solutions must create a custom import job for each distributor. To discuss the specific contents and format for your demographics data, please contact Tim Ulrich (timu@180solutions.com).
Written by:
Ken Smith (kens@180solutions.com)
Updated on April 3, 2003
Abstract
This paper provides a brief description of the n-CASE client, and outlines the requirements and alternatives for integrating the n-CASE client into your own application.
Table of Contents
n-CASETM Client Integration 1
INTRODUCTION 1
Components 1
Client 1
Identity Server 1
Profile Server 1
Control Interface 1
Terminology 1
Distributors 1
Subscribers 2
WHAT THE N-CASE CLIENT DOES 3
Description 3
Self-Registration 3
Ad Display 3
Data Collection 4
Automatic Update 4
HOW TO INTEGRATE THE N-CASE CLIENT 5
#1: Bundle the n-CASE Client With Your Setup 5
#2: Generate and Store a Unique Identifier 5
#3: Launch the n-CASE Client And Pass the Unique Identifier 6
INTRODUCTION
Components
The components of the 180Solutions n-CASE include the following:
Client
The n-CASE Client is a client-side Win32 application which serves as the primary communication point between the client and the n-CASE Identity Server as well as the primary data collection point. The n-CASE Client registers pseudonymous unique identifiers with the n-CASE Identity Server, collects and uploads click-stream, demographic and psychographic user data, and periodically displays advertisements and survey questions in compliance with the intent of P3P. The n-CASE client is described in more detail below.
Identity Server
The n-CASE Identity Server (n-CIS) is a server-side system which serves to pseudonymously and uniquely identify individuals, collect user data uploaded by the n-CASE Client, and aggregates demographic data to compile detailed predictive customer data.
Profile Server
The n-CASE Profile Server (n-CPS) redistributes predictive customer data (through various mechanisms) to Subscribers for use in pseudonymous analysis, pseudonymous decision, one-time tailoring or affirmative customization.
Control Interface
The n-CASE Control Interface (n-CCI) is a web-based interface which allows Subscribers to define their own demographics categories and pass-through HTML or XML templates.
Terminology
Distributors
Distributors are companies that have agreed to distribute the n-CASE client-side component. This component will be included in the distributor’s client-side applications, and will be used to pseudonymously and uniquely identify the user and to gather clickstream data. (See page 5 for a discussion of privacy issues.) Additionally, the demographics data that distributors collect from users will be collated and aggregated with the existing 180Solutions profile data. Each distributor is assigned a unique Distributor ID.
Subscribers
Subscribers are companies who use the n-CASE profile data to enhance users’ experience on their own web site: either through improved ad targeting, or through integration with their own personalization engines. Each Subscriber is assigned a unique Subscriber ID.
For More Inforation
For more information on n-CASE and the associated suite of technologies, see our white paper, posted at:
http://www.180solutions.com/n-case/n-case_whitepaper.doc
WHAT THE N-CASE CLIENT DOES
Description
The n-CASE client is a Win32 executable, and runs in a separate process from the Distributor’s application (as opposed to being implemented as a DLL or COM object). The primary reason for this is to make integration as easy as possible. Our goal was to require as few changes as possible – and in some instances, none whatsoever – to the Distributor’s application.
Self-Registration
The Distributor’s application will launch the n-CASE for the first time – either during setup, or later, after some sort of registration process has taken place. The n-CASE client typically takes a number of parameters, two of which are most important: “DID” (for Distributor ID), and “DUID” (for Distributor User ID). Each time the n-CASE client is launched with these two parameters, it takes the following actions:
(1) Writes the DID/DUID to the registry.
(2) Sets itself to run automatically on startup.
(3) Checks for an Internet connection, and as soon as one is available, contacts the n-CASE Configuration Server for configuration information.
(4) Posts the DID and DUID to the n-CASE Configuration Server.
(5) Receives a cookie from the n-CASE Configuration Server which is associated with that DID/DUID combination.
(6) Writes that cookie to the user’s browser(s).
It should be noted that if the n-CASE client is launched with a DID but not a DUID, it will contact the n-CASE Configuration Server to receive an automatically generated, random 30-character DUID.
Ad Display
One of the configuration details the n-CASE client receives from the configuration server is how often it should display a pop-up ad. This interval may range from once every 15 minutes to once every couple of days, and is set at the discretion of the Distributor. When that interval has passed, and the n-CASE client detects that an Internet connection is available, it displays a pop-up ad, targeted to that specific user.
Data Collection
While the user is connected to the Internet, the n-CASE client tracks clickstream data, and periodically uploads it to the n-CASE Identity Server. Before doing so, it checks to make sure that (a) an Internet connection is available, and (b) that it is not being highly utilized. When these conditions are met, it then performs its uploads in the background, batching the data before transmission, so that the user’s normal work is not affected.
Automatic Update
Once a day, the n-CASE client checks with the n-CASE Configuration Server to see if a new version is available. If there is, it downloads the new version, confirms a checksum on the downloaded file, replaces itself, launches the new version, and shuts itself down.
HOW TO INTEGRATE THE N-CASE CLIENT
To integrate the n-CASE client into your application, there are only three very simple things you need to do.
#1: Bundle the n-CASE Client With Your Setup
The n-CASE client must be installed in a directory other than that of your application. We recommend creating an “n-CASE” folder under “program files”. The application name is “msbb.exe”, and will be provided to you by 180Solutions. Also, your setup program must clearly message to users what n-CASE will do on their systems and give them the ability to terminate the installation. You may use opt-in or opt-out methods and you may require that users install n-CASE in order to install your application.
#2: Generate and Store a Unique Identifier
This step may not be required in some instances, but there are a number of benefits associated with it. If your contract requires sharing demographic information about your users with 180Solutions, it is a requirement.
This UID should not be anything that could personally identify the user, such as an email address or a user-chosen userid. The UID is limited to 30 characters and may include any ANSI character except “&”, “%”, and <space>.
If your application does not have the ability to communicate with a centralized server and thus choose a UID which is guaranteed unique throughout your namespace, and if you are not providing 180Solutions with demographic data, it is acceptable to have your application create a “statistically” unique UID, i.e., 30 random characters; or alternatively, by passing in a DID value but no DUID parameter. In this latter instance, the n-CASE client will request a randomly generated DUID from the n-CASE Configuration Server.
Once you have generated this UID, you should store it in the Windows Registry so that it may be permanently associated with this installation of your application.
#3: Launch the n-CASE Client And Pass the Unique Identifier
In most instances, your application should launch the n-CASE client as follows:
C:\MyAppDir\msbb.exe /did=DistributorID /duid=UniqueIdentifier
Your application only needs to successfully launch the n-CASE client once, preferably during your application’s installation process. For details about what the n-CASE client does once launched, see above.
And again, if you pass in a DID but no DUID, the n-CASE client will automatically request a randomly generated DUID from the n-CASE Configuration Server. However, this is not generally recommended, as it doesn’t allow for the sharing of specific demographic and usage information.
Note on CBC compliance:
If you wish to run in a fully CBC compliant mode, you must save the ncase.ini file to the user’s computer. Save this in the same folder as the n-CASE executable with the name “ncase.ini”. Your application should then launch n-CASE as follows:
C:\MyAppDir\msbb.exe /cbc=init /did=DistributorID /duid=UniqueIdentifier
This will prompt the user with the appropriate CBC wording. If you wish to edit the .INI file, please forward any changes for our review. Be aware that there is a limit to the size of this .ini file. The current file already meets that limit.
SHARING DEMOGRAPHICS INFORMATION
The deals that we negotiate with most Distributors require that they share with us whatever demographic data they collect about their customers. This is done by FTP-ing the demographics information for each day’s new users in comma-separated value (CSV) format to:
ftp://ftp.180solutions.com/demog/company_name/yyyymmdd.txt
Each text field in the file should be enclosed in double quotation marks (with any quotation marks within the text of the field double-quoted, i.e., “Toys-“”R””-Us”). Each record should be terminated with both a Carriage-Return and a Line-Feed character (chr(13) + chr(10)). (This is standard for Windows and similar systems, but must be specifically configured on Unix-based operating systems.)
Since the demographic information each distributor collects will be different, and the format for the information will vary from distributor to distributor, 180Solutions must create a custom import job for each distributor. To discuss the specific contents and format for your demographics data, please contact Tim Ulrich (timu@180solutions.com).
