=head1 NAME BeeQueen
=head2 SYNOPSIS Cloud advertisement processor (CAP).
This module intends for advertising message processing, which are sent to us by CS (client service). CS might be a site, sites or a mobile application. Processing means next 3 functions:
=over 5
=item * Registration of advertising messages in a DB;
=item * Returning proper (set by a client) response on demand;
=item * That`s all.
=back
=head2 Registration of advertising messages in the DB.
When CAP accepts one of three kinds of requests, it immediate puts it with all its properties to the DB.
There are 3 types of requests:
=over 5
=item Impression*: a user service has just requested us to show an ad banner, consists of 2 parameters: user_id, target_id;
=item Click* request: a user has just clicked to a banner in CS and his browser has sent request to CAP, consists of 3 parameters: user_id, target_id and banner_id;
=item Endpoint* request: a user has just do some event, in which an owner of CS is interested in (a user buy anything for example), consists of 2 parameters: user_id and event_type.
=back
=head3 Something about parameters:
=over 5
=item user_id allows us to identify user, for who CS wants show ad banner. user_id* is produced by CS service as 32 byte array of symbols.
=item target_id* identifies target, which represents advertising place in application or site itself, it is 32 byte array of symbols also;
=item banner_id* identifies advertising banner, not just a picture, but picture with all configurations, 32 byte array of symbols;
=item event_type* is just a message intended to identify type of an endpoint action for our client, it might be a 255 bytes string.
=back
=head2 Returning proper (predicted by client) response on demand.
We must obviously return something for client requests. Generally CAP uses HTTP Response Statuses to transport information into response;
=over 5
=item After impression* requests CAP returns URL to static (banner image);
=item After click* request CAP redirects a user to target URL (web page probably);
=item After endpoint* request CAP returns empty message.
=back
If response has body information, this information is formatted as JSON Object. Because we might add any new parameters to response in future.
=head3 Callbacks
I believe it is sellable feature. CAP may call some client URLs as a part of endpoint request processing. Client compose URL which must be called when some request processed successfully in client console. He prepares URL template, it looks like
http://pornstarsgals.com/new/client/buy/smthg?userid=%USER_ID%
It may be useful for client to react for events, for example to pay poker chips to user who install application from poker with a help of CAP.
=head3 Impression strategy
When CAP is processing impression request, it must determine, which banner will be showed to user.
Generally CAP uses Fitness_proportionate_selection for it.
User have to create a target, banners and tune, which banners impress in the target and how often in persentes.
=head3 Objects
It is not objects in OOP meaning, but object in real life.
user: email: ilaymirin@pornstarsgals.com name: ilaymirin targets:
=head3 Interface
CAP believes in REST
For example, a typical click processing call:
POST http://tripping-ninja.com/v2/click user_id=23gfh3j9hf3xm8fm38yxgfm38xmbf3c target_id=23gfh3j9hf3xm8fm38yxgfm38xmbf3c banner_id=23gfh3j9hf3xm8fm38yxgfm38xmbf3c`
Get the whole information about banner, throw target:
GET http://tripping-ninja.com/v2/banner/23gfh3j9hf3xm8fm38yxgfm38xmbf3c/target/23gfh3j9hf3xm8fm38yxgfm38xmbf3c [ { id: "dvsvsbsbdbdb", banner_id: "23gfh3j9hf3xm8fm38yxgfm38xmbf3c", target_id: "svsvsvscvdfewfwefwfwfwfwfwdvbev", user_id: "wvwinviwjnvwdnmvwodmckmwdocmcwo", created_at: "2013-01-01 01:11:75" }, etc... ]
=cut