Bitrix Site Manager

CAdv::GetList

CDBResult
CAdv::GetList(
 string &by = "SESSIONS",
 string &order = "desc",
 array filter = array(),
 bool &is_filtered,
 mixed limit = "",
 array &referer_group,
 string &sql
)

The method GetList returns the list of advertising campaigns (AC) containing the calculated statistical figures and all the information about traffic.

Parameters

Parameter Description
by Sorting field. Possible values:
  • ID - the ID of the advertising campaign;
  • PRIORITY - priority;
  • REFERER1 - the referer1 identifier of the AC;
  • REFERER2 - the referer2 identifier of the AC;
  • C_TIME_FIRST - date and time when the AC started (the first direct hit);
  • C_TIME_LAST - the last direct hit or return under the AC;
  • ADV_TIME - duration of the AC (difference C_TIME_LAST - C_TIME_FIRST);
  • ATTENT - rate of attentiveness of visitors on direct hit under this AC;
  • ATTENT_BACK - rate of attentiveness of returned visitors under this AC;
  • NEW_VISITORS - ratio of visitors who first entered the site under this AC to the total number of those entered the site under this AC;
  • RETURNED_VISITORS - percent of visitors who returned to the site after the direct hit under this AC;
  • VISITORS_PER_DAY - average number of visitors per day;
  • COST - expenses for the AC;
  • REVENUE - revenue of the AC;
  • BENEFIT - profit of the AC;
  • ROI - profitability of the AC;
  • SESSION_COST - average cost of session (expenses to the number of sessions on direct hit);
  • VISITOR_COST - average cost of a visitor (expenses to the number of visitors on direct hit);
  • GUESTS - total number of direct hit visitors;
  • GUESTS_BACK - total number of returned visitors;
  • NEW_GUESTS - total number of new visitors who entered the site under this AC;
  • FAVORITES - total number of the direct hit visitors who added the site to Favorites when entered under this AC;
  • FAVORITES_BACK - total number of visitors who added the site to Favorites when returned under this AC;
  • C_HOSTS - total number of hosts on direct hit under the AC;
  • HOSTS_BACK - total number of the on-return hosts under the AC;
  • SESSIONS - total number of sessions on direct hit under the AC;
  • SESSIONS_BACK - total number of the on-return sessions under the AC;
  • HITS - total number of the direct hits under the AC;
  • HITS_BACK - total number of the on-return hits under the AC;
  • GUESTS_TODAY - number of the direct hit visitors for today;
  • GUESTS_BACK_TODAY - number of the returned visitors for today;
  • NEW_GUESTS_TODAY - number of the new visitors for today;
  • FAVORITES_TODAY - number of the direct hit visitors who added the site to Favorites for today;
  • FAVORITES_BACK_TODAY - number of the returned visitors who added the site to Favorites for today;
  • C_HOSTS_TODAY - number of the direct hit hosts for today;
  • HOSTS_BACK_TODAY - number of the on-return hosts for today;
  • SESSIONS_TODAY - number of the direct hit sessions for today;
  • SESSIONS_BACK_TODAY - number of the on-return sessions for today;
  • HITS_TODAY - number of direct hits for today;
  • HITS_BACK_TODAY - number of on-return hits for today;
  • GUESTS_YESTERDAY - number of the direct hit visitors for yesterday;
  • GUESTS_BACK_YESTERDAY - number of the returned visitors for yesterday;
  • NEW_GUESTS_YESTERDAY - number of the new visitors for yesterday;
  • FAVORITES_YESTERDAY - number of the direct hit visitors who added the site to Favorites for yesterday;
  • FAVORITES_BACK_YESTERDAY - number of the returned visitors who added the site to Favorites for yesterday;
  • C_HOSTS_YESTERDAY - number of the direct hit hosts for yesterday;
  • HOSTS_BACK_YESTERDAY - number of the on-return hosts for yesterday;
  • SESSIONS_YESTERDAY - number of the direct hit sessions for yesterday;
  • SESSIONS_BACK_YESTERDAY - number of the on-return sessions for yesterday;
  • HITS_YESTERDAY - number of direct hits for yesterday;
  • HITS_BACK_YESTERDAY - number of on-return hits for yesterday;
  • GUESTS_BEF_YESTERDAY - number of the direct hit visitors for the day before yesterday;
  • GUESTS_BACK_BEF_YESTERDAY - number of the returned visitors for the day before yesterday;
  • NEW_GUESTS_BEF_YESTERDAY - number of the new visitors for the day before yesterday;
  • FAVORITES_BEF_YESTERDAY - number of the direct hit visitors who added the site to Favorites for the day before yesterday;
  • FAVORITES_BACK_BEF_YESTERDAY - number of the returned visitors who added the site to Favorites for the day before yesterday;
  • C_HOSTS_BEF_YESTERDAY - number of the direct hit hosts for the day before yesterday;
  • HOSTS_BACK_BEF_YESTERDAY - number of the on-return hosts for the day before yesterday;
  • SESSIONS_BEF_YESTERDAY - number of the direct hit sessions for the day before yesterday;
  • SESSIONS_BACK_BEF_YESTERDAY - number of the on-return sessions for the day before yesterday;
  • HITS_BEF_YESTERDAY - number of direct hits for the day before yesterday;
  • HITS_BACK_BEF_YESTERDAY - number of on-return hits for the day before yesterday;
  • GUESTS_PERIOD - number of the direct hit visitors within the time period specified in the filter;
  • GUESTS_BACK_PERIOD - number of the returned visitors within the time period specified in the filter;
  • NEW_GUESTS_PERIOD - number of the new visitors within the time period specified in the filter;
  • FAVORITES_PERIOD - number of the direct hit visitors who added the site to Favorites within the time period specified in the filter;
  • FAVORITES_BACK_PERIOD - number of the returned visitors who added the site to Favorites within the time period specified in the filter;
  • C_HOSTS_PERIOD - number of the direct hit hosts within the time period specified in the filter;
  • HOSTS_BACK_PERIOD - number of the on-return hosts within the time period specified in the filter;
  • SESSIONS_PERIOD - number of the direct hit sessions within the time period specified in the filter;
  • SESSIONS_BACK_PERIOD - number of the on-return sessions within the time period specified in the filter;
  • HITS_PERIOD - number of direct hits within the time period specified in the filter;
  • HITS_BACK_PERIOD - number of on-return hits within the time period specified in the filter.
order Sort order. Possible values:
  • asc - ascending;
  • desc - descending.
filter Array used to filter the resulting list. The following keys are possible in this array:
  • GROUP - list of possible values:
    • referer1 - the AC list will be grouped by the referer1 identifier of the AC;
    • referer2 - the AC list will be grouped by the referer2 identifier of the AC.
  • ID* - the ID of the AC;
  • ID_EXACT_MATCH - if set to "N", the ID can be an entry in the identifier string (loose match);
  • DATE1_PERIOD - minimum value of the period for which the information is to be obtained;
  • DATE2_PERIOD - maximum value of the period for which the information is to be obtained;
  • DATE1_FIRST - first value of the range to match against the field "AC starting date";
  • DATE2_FIRST - last value of the range to match against the field "AC starting date";
  • DATE1_LAST - first value of the range to match against the field "AC ending date";
  • DATE2_LAST - last value of the range to match against the field "AC ending date";
  • REFERER1* - the referer1 identifier of the AC;
  • REFERER1_EXACT_MATCH - if set to "Y", the REFERER1 must match exactly;
  • REFERER2* - the referer2 identifier of the AC;
  • REFERER2_EXACT_MATCH - if set to "Y", the REFERER2 must match exactly;
  • PRIORITY1 - first value of the range to match against the field "AC Priority";
  • PRIORITY2 - last value of the range to match against the field "AC Priority";
  • NEW_GUESTS1 - first value of the range to match against the field "AC new visitors";
  • NEW_GUESTS2 - last value of the range to match against the field "AC new visitors";
  • GUESTS_BACK - tells by which field visitors are to be sorted:
    • N - on direct hit;
    • Y - on return.
  • GUESTS1 - first value of the range to match against the field "Direct-hit or on-return visitors" (depends on the GUESTS_BACK state flag);
  • GUESTS2 - last value of the range to match against the field "Direct-hit or on-return visitors" (depends on the GUESTS_BACK state flag);
  • FAVORITES_BACK - tells by which field visitors who added the site to Favorites are to be sorted:
    • N - on direct hit;
    • Y - on return.
  • FAVORITES1 - first value of the range to match against the field "Direct-hit or on-return visitors who added the site to Favorites" (depends on the FAVORITES_BACK state flag);
  • FAVORITES2 - last value of the range to match against the field "Direct-hit or on-return visitors who added the site to Favorites" (depends on the FAVORITES_BACK state flag);
  • HOSTS_BACK - tells how hosts are to be sorted:
    • N - on direct hit;
    • Y - on return.
  • HOSTS1 - first value of the range to match against the field "Direct-hit or on-return hosts" (depends on the HOSTS_BACK state flag);
  • HOSTS2 - last value of the range to match against the field "Direct-hit or on-return hosts" (depends on the HOSTS_BACK state flag);
  • SESSIONS_BACK - tells how sessions are to be sorted:
    • N - on direct hit;
    • Y - on return.
  • SESSIONS1 - first value of the range to match against the field "Direct-hit or on-return sessions" (depends on the SESSIONS_BACK state flag);
  • SESSIONS2 - last value of the range to match against the field "Direct-hit or on-return sessions" (depends on the SESSIONS_BACK state flag)
  • HITS_BACK - tells how hits are to be sorted:
    • N - on direct hit;
    • Y -  on return.
  • HITS1 - first value of the range to match against the field "Direct or on-return hits" (depends on the HITS_BACK state flag);
  • HITS2 - last value of the range to match against the field "Direct or on-return hits" (depends on the HITS_BACK state flag);
  • COST1 - first value of the range to match against the field "AC expenses";
  • COST2 - last value of the range to match against the field "AC expenses";
  • REVENUE1 - first value of the range to match against the field "AC revenue";
  • REVENUE2 - last value of the range to match against the field "AC revenue";
  • BENEFIT1 - first value of the range to match against the field "AC profit";
  • BENEFIT2 - last value of the range to match against the field "AC profit";
  • ROI1 - first value of the range to match against the field  "AC profitability";
  • ROI2 - last value of the range to match against the field "AC profitability";
  • ATTENT1 - first value of the range to match against the field  "Rate of attentiveness of AC visitors";
  • ATTENT2 - last value of the range to match against the field "Rate of attentiveness of AC visitors";
  • VISITORS_PER_DAY1 - first value of the range to match against the field "Average number of visitors per day";
  • VISITORS_PER_DAY2 - last value of the range to match against the field "Average number of visitors per day";
  • DURATION1 - first value of the range to match against the field  "AC duration";
  • DURATION2 - last value of the range to match against the field "AC duration";
  • CURRENCY - currency of the AC financial figures;
  • DESCRIPTION* - description of the AC;
  • DESCRIPTION_EXACT_MATCH - if set to "Y", the DESCRIPTION must match exactly.
* - complex logic is allowed
is_filtered If this variable contains "true" on return, the resulting list is filtered.
limit Maximum number of the AC's to return. If set to "", the number of AC's will be limited to that specified in the parameter Maximum number of records displayed in tables in the Statistics module settings.
referer_group Reference to an array initialised only if grouping by referer1 or referer2 (if filter["GROUP"]="referer1" or filter["GROUP"]="referer2"). The array has the following structure:
[referer1 or referer2] => Array
    (
        [REFERER1] => referer1 or
        [REFERER2] => referer2
        
        [GUESTS_TODAY] => number of the direct hit visitors for today
        [GUESTS_BACK_TODAY] => number of the returned visitors for today
        [NEW_GUESTS_TODAY] => number of the new visitors for today
        [FAVORITES_TODAY] => number of the direct hit visitors
                             who added the site to Favorites for today
        [FAVORITES_BACK_TODAY] => number of the returned visitors 
                                  who added the site to Favorites for today
        [C_HOSTS_TODAY] => number of the direct hit hosts for today
        [HOSTS_BACK_TODAY] => number of the on-return hosts for today
        [SESSIONS_TODAY] => number of the direct hit sessions for today
        [SESSIONS_BACK_TODAY] => number of the on-return sessions for today
        [HITS_TODAY] => number of direct hits for today
        [HITS_BACK_TODAY] => number of on-return hits for today

        [GUESTS_YESTERDAY] => number of the direct hit visitors for yesterday
        [GUESTS_BACK_YESTERDAY] => number of the returned visitors for yesterday
        [NEW_GUESTS_YESTERDAY] => number of the new visitors for yesterday
        [FAVORITES_YESTERDAY] => number of the direct hit visitors
                                 who added the site to Favorites for yesterday
        [FAVORITES_BACK_YESTERDAY] => number of the returned visitors 
                                      who added the site to Favorites for yesterday
        [C_HOSTS_YESTERDAY] => number of the direct hit hosts for yesterday
        [HOSTS_BACK_YESTERDAY] => number of the on-return hosts for yesterday
        [SESSIONS_YESTERDAY] => number of the direct hit sessions for yesterday
        [SESSIONS_BACK_YESTERDAY] => number of the on-return sessions for yesterday
        [HITS_YESTERDAY] => number of direct hits for yesterday
        [HITS_BACK_YESTERDAY] => number of on-return hits for yesterday

        [GUESTS_BEF_YESTERDAY] => number of the direct hit visitors for the day before yesterday
        [NEW_GUESTS_BEF_YESTERDAY] => number of the new visitors for the day before yesterday
        [FAVORITES_BEF_YESTERDAY] => number of the direct hit visitors
                                     who added the site to Favorites for the day before yesterday
        [C_HOSTS_BEF_YESTERDAY] => number of the direct hit hosts for the day before yesterday
        [SESSIONS_BEF_YESTERDAY] => number of the direct hit sessions for the day before yesterday
        [HITS_BEF_YESTERDAY] => number of direct hits for the day before yesterday
        [GUESTS_BACK_BEF_YESTERDAY] => number of the returned visitors for the day before yesterday
        [FAVORITES_BACK_BEF_YESTERDAY] => number of the returned visitors 
                                          who added the site to Favorites for the day before yesterday
        [HOSTS_BACK_BEF_YESTERDAY] => number of the on-return hosts for the day before yesterday
        [SESSIONS_BACK_BEF_YESTERDAY] => number of the on-return sessions for the day before yesterday
        [HITS_BACK_BEF_YESTERDAY] => number of on-return hits for the day before yesterday

        [GUESTS_PERIOD] => number of the direct hit visitors for the time period
            (time period is set by initialising:
            filter["DATE1_PERIOD"] and/or filter["DATE2_PERIOD"])
        [GUESTS_BACK_PERIOD] => number of the returned visitors for the time period
        [NEW_GUESTS_PERIOD] => number of the new direct hit visitors for the time period
        [C_HOSTS_PERIOD] => number of the direct hit hosts for the time period
        [HOSTS_BACK_PERIOD] => number of the on-return hosts for the time period
        [FAVORITES_PERIOD] => number of the direct hit visitors
                              who added the site to Favorites for the time period
        [FAVORITES_BACK_PERIOD] => number of the returned visitors
                                   who added the site to Favorites for the time period
        [SESSIONS_PERIOD] => number of the direct hit sessions for the time period
        [SESSIONS_BACK_PERIOD] => number of the on-return sessions for the time period
        [HITS_PERIOD] => number of direct hits for the time period
        [HITS_BACK_PERIOD] => number of on-return hits for the time period
    )        
sql Reference to the resulting SQL query used to select advertising campaigns.

Structure of the returned record

Array
(
    [ID] => ID
    [PRIORITY] => priority
    [REFERER1] => the referer1 identifier
    [REFERER2] => the referer2 identifier
    [DESCRIPTION] => description
    [EVENTS_VIEW] => the event list display mode, possible values are:
        link - as a link to the list
        list - as a list
        event1 - grouped by event1
        event2 - grouped by event2

    [DATE_FIRST] => date and time of the first direct hit
    [DATE_LAST] => date and time of the last direct hit or return
    [ADV_TIME] => duration of the AC, in seconds

    [ATTENT] => rate of attentiveness of the direct hit visitors
    [ATTENT_BACK] => rate of attentiveness of the returned visitors
    [NEW_VISITORS] => percentage of new visitors
    [RETURNED_VISITORS] => percent of the direct hit visitors who returned to the site
    [VISITORS_PER_DAY] => average number of visitors per day

    [CURRENCY] => currency of financial figures
    [COST] => expenses
    [REVENUE] => revenue
    [BENEFIT] => profit
    [SESSION_COST] => cost of a session
    [VISITOR_COST] => cost of a visitor
    [ROI] => profitability

    [GUESTS] => total number of direct hit visitors
    [NEW_GUESTS] => total number of new direct hit visitors
    [FAVORITES] => total number of direct hit visitors who added the site to Favorites
    [C_HOSTS] => total number of direct hit hosts
    [SESSIONS] => total number of direct hit sessions
    [HITS] => total number of direct hits
    [GUESTS_BACK] => total number of returned visitors
    [FAVORITES_BACK] => total number of returned visitors who added the site to Favorites
    [HOSTS_BACK] => total number of on-return hosts
    [SESSIONS_BACK] => total number of on-return sessions
    [HITS_BACK] => total number of on-return hits

    [GUESTS_TODAY] => total number of direct hit visitors for today
    [GUESTS_BACK_TODAY] => total number of returned visitors for today
	[NEW_GUESTS_TODAY] => total number of new direct hit visitors for today
    [FAVORITES_TODAY] => total number of direct hit visitors who added the site to Favorites for today
    [FAVORITES_BACK_TODAY] => total number of returned visitors who added the site to Favorites for today
	[C_HOSTS_TODAY] => total number of direct hit hosts for today
    [HOSTS_BACK_TODAY] => total number of on-return hosts for today
	[SESSIONS_TODAY] => total number of direct hit sessions for today
    [SESSIONS_BACK_TODAY] => total number of on-return sessions for today
	[HITS_TODAY] => total number of direct hits for today
    [HITS_BACK_TODAY] => total number of on-return hits for today

    [GUESTS_YESTERDAY] => total number of direct hit visitors for yesterday
    [GUESTS_BACK_YESTERDAY] => total number of returned visitors for yesterday
	[NEW_GUESTS_YESTERDAY] => total number of new direct hit visitors for yesterday
    [FAVORITES_YESTERDAY] => total number of direct hit visitors who added the site to Favorites for yesterday
    [FAVORITES_BACK_YESTERDAY] => total number of returned visitors who added the site to Favorites for yesterday
	[C_HOSTS_YESTERDAY] => total number of direct hit hosts for yesterday
    [HOSTS_BACK_YESTERDAY] => total number of on-return hosts for yesterday
	[SESSIONS_YESTERDAY] => total number of direct hit sessions for yesterday
    [SESSIONS_BACK_YESTERDAY] => total number of on-return sessions for yesterday
	[HITS_YESTERDAY] => total number of direct hits for yesterday
    [HITS_BACK_YESTERDAY] => total number of on-return hits for yesterday

    [GUESTS_BEF_YESTERDAY] => total number of direct hit visitors for the day before yesterday
    [GUESTS_BACK_BEF_YESTERDAY] => total number of returned visitors for the day before yesterday
	[NEW_GUESTS_BEF_YESTERDAY] => total number of new direct hit visitors for the day before yesterday
    [FAVORITES_BEF_YESTERDAY] => total number of direct hit visitors who added the site to Favorites for the day before yesterday
    [FAVORITES_BACK_BEF_YESTERDAY] => total number of returned visitors who added the site to Favorites for the day before yesterday
	[C_HOSTS_BEF_YESTERDAY] => total number of direct hit hosts for the day before yesterday
    [HOSTS_BACK_BEF_YESTERDAY] => total number of on-return hosts for the day before yesterday
	[SESSIONS_BEF_YESTERDAY] => total number of direct hit sessions for the day before yesterday
    [SESSIONS_BACK_BEF_YESTERDAY] => total number of on-return sessions for the day before yesterday
	[HITS_BEF_YESTERDAY] => total number of direct hits for the day before yesterday
    [HITS_BACK_BEF_YESTERDAY] => total number of on-return hits for the day before yesterday

    [GUESTS_PERIOD] => total number of direct hit visitors for the period
    [GUESTS_BACK_PERIOD] => total number of returned visitors for the period
	[NEW_GUESTS_PERIOD] => total number of new direct hit visitors for the period
    [FAVORITES_PERIOD] => total number of direct hit visitors who added the site to Favorites
        for the period
    [FAVORITES_BACK_PERIOD] => total number of returned visitors who added the site to Favorites
        for the period
	[C_HOSTS_PERIOD] => total number of direct hit hosts for the period
    [HOSTS_BACK_PERIOD] => total number of on-return hosts for the period
	[SESSIONS_PERIOD] => total number of direct hit sessions for the period
    [SESSIONS_BACK_PERIOD] => total number of on-return sessions for the period
	[HITS_PERIOD] => total number of direct hits for the period
    [HITS_BACK_PERIOD] => total number of on-return hits for the period
)

See Also

Example



<?
// filter by advertising campaigns whose referer1 contains "google"
// and obtain the additional information for December 2005
$arFilter = array(
    "REFERER1"     => "google",
    "DATE1_PERIOD" => "01.12.2005",
    "DATE2_PERIOD" => "31.12.2005"
    );

// obtain the set of records
$rs = CAdv::GetList(
    ($by="SESSIONS"), 
    ($order="desc"), 
    $arFilter, 
    $is_filtered,
    "",
    $referer_group,
    $sql
    );

// print all the records
while ($ar = $rs->Fetch())
{
    echo "<pre>"; print_r($ar); echo "</pre>";    
}
?>