/BeeQueen

Cloud advertisement processor (Perl version)

Primary LanguagePerl

=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](http://en.wikipedia.org/wiki/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:
  - id: 23gfh3j9hf3xm8fm38yxgfm38xmbf3c
    name: Big banner with girls
    banners:
      - id: ds3fh93r9f3rjf3r9f39rn93rnwcwdcw
        name: boobs1
        prob: 0.7
        target_url: http://pornstarsgals.com/big/boobs/3439849w2384
      - id: 3nvu3nviejnfvijefnviefmvjefvkevj
        name: boobs2
        prob: 0.3
        target_url: http://pornstarsgals.com/big/booties/245243423423
    endpoints: 
      - name: user_buy_somthg
        callback: http://pornstarsgals.com/new/client/buy/smthg?userid=%USER_ID%
      - name: user_watch_big_photo


=head3 Interface

CAP believes in [REST](http://www.restapitutorial.com/lessons/whatisrest.html)

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