Interface Inx_Api_DataAccess_ClickDataQuery

Description

Inx_Api_DataAccess_ClickDataQuery provides a fluent interface for retrieving click data. to filter the clicks:

  • mailing ID(s)
  • link ID(s)
  • recipient ID(s)
  • link type(s)
  • start date
  • end date
  • sending ID(s) (since API 1.
Each filter is assigned by calling the corresponding method. either a single int or as an int[] by choosing the appropriate method (singular versus plural). is true for the link types. concise as possible.

Inx_Api_DataAccess_ClickDataQuery provides a fluent interface for retrieving click data. The following criteria can be used to filter the clicks:

  • mailing ID(s)
  • link ID(s)
  • recipient ID(s)
  • link type(s)
  • start date
  • end date
  • sending ID(s) (since API 1.12.1)
Each filter is assigned by calling the corresponding method. All filters can be freely combined. IDs can be given as either a single int or as an int[] by choosing the appropriate method (singular versus plural). The same is true for the link types. This allows the creation of complex queries while the fluent interface keeps the syntax as concise as possible. Note: Each filter may only be applied once. For example, it is not possible to create a query that retrieves all clicks of two time periods (e.g. all clicks performed during February and during September). However, applying a filter twice (i.e. calling the corresponding method twice) is not an error. The last application (method call) of the filter will always overwrite all previous applications.

Important note: The Inxmail Professional server will terminate any ClickDataQuery request that produces an overall result size of over ten million clicks, by default. Any request with a result size above this threshold will result in a server-side RuntimeException.

The following snippet demonstrates how simple it is to retrieve all clicks which have been performed after a certain date. The last two lines show the actual creation and execution of the query:

 $oRecipientContext = $oSession->createRecipientContext();
 $aAttrs = array( $oRecipientContext->getMetaData()->getEmailAttribute() );
 $sStart = date( 'c', strtotime( '-1 day ) );

 $oClickDataQuery = $oSession->getDataAccess()->getClickData()->createQuery( $oRecipientContext, $aAttrs );
 $oClickDataRowSet = $oClickDataQuery->after( $sStart )->executeQuery();
To demonstrate the power of this approach, the following snippet combines most of the available filters, thus retrieving all clicks for the given mailings, recipients and link types, which occurred during February 2013:
 $oRecipientContext = $oSession->createRecipientContext();
 $aAttrs = array( $oRecipientContext->getMetaData()->getEmailAttribute() );
 $sStart = date( 'c', mktime( 0, 0, 0, 2, 1, 2013 ) );
 $sEnd = date( 'c', mktime( 23, 59, 59, 2, 23, 2013 ) );

 $aMailingIds = array( 1234, 4711 );
 $aRecipientIds = array( 2, 3, 5, 7, 11, 13, 17 );
 $aLinkTypes = array( Inx_Api_DataAccess_LinkDataRowSet::LINK_TYPE_UNIQUE_COUNT,
      Inx_Api_DataAccess_LinkDataRowSet::LINK_TYPE_OPENING_COUNT );

 $oClickDataQuery = $oSession->getDataAccess()->getClickData()->createQuery( $oRecipientContext, $aAttrs );
 $oClickDataRowSet = $oClickDataQuery->mailings( $aMailingIds )->recipients( $aRecipientIds )->linkTypes(
      $aLinkTypes )->between( $sStart, $sEnd )->executeQuery();
Note: Usually, it makes no sense to filter by mailing or link type when you are already filtering by individual links, as this is just redundant information. Therefore the example above did not filter by any links. This can be achieved analogical.

For more information about click data, see the Inx_Api_DataAccess_ClickData documentation.

Located in /Api/DataAccess/ClickDataQuery.php (line 69)


	
			
Method Summary
Methods
after (line 192)

Assigns an after filter (start date), overwriting any existing after filters, including those imposed by between filters.

Assigns an after filter (start date), overwriting any existing after filters, including those imposed by between filters. The result will only contain clicks performed after or at the given date.

  • return: this query.
  • access: public
Inx_Api_DataAccess_ClickDataQuery after (string $sDate)
  • string $sDate: the date by which the result shall be filtered, inclusively. The date has to be specified as ISO-8601 formatted datetime string.
before (line 181)

Assigns a before filter (end date), overwriting any existing before filters, including those imposed by between filters.

Assigns a before filter (end date), overwriting any existing before filters, including those imposed by between filters. The result will only contain clicks performed before or at the given date.

  • return: this query.
  • access: public
Inx_Api_DataAccess_ClickDataQuery before (string $sDate)
  • string $sDate: the date by which the result shall be filtered, inclusively. The date has to be specified as ISO-8601 formatted datetime string.
between (line 205)

Assigns a between filter (start and end date), overwriting any existing before, after and between filters. result will only contain clicks performed after or at the given start date and before or at the given end date.

Assigns a between filter (start and end date), overwriting any existing before, after and between filters. The result will only contain clicks performed after or at the given start date and before or at the given end date.

  • return: this query.
  • access: public
Inx_Api_DataAccess_ClickDataQuery between (string $sStart, string $sEnd)
  • string $sStart: the start date by which the result shall be filtered, inclusively. The date has to be specified as ISO-8601 formatted datetime string.
  • string $sEnd: the end date by which the result shall be filtered, inclusively. The date has to be specified as ISO-8601 formatted datetime string.
executeQuery (line 217)

Executes the query, applying all filters and returning the resulting ClickDataRowSet.

Executes the query, applying all filters and returning the resulting ClickDataRowSet. Important note: The Inxmail Professional server will terminate any ClickDataQuery request that produces an overall result size of over ten million clicks, by default. Any request with a result size above this threshold will result in a server-side RuntimeException.

  • return: a ClickDataRowSet object that contains the data produced by this query.
  • access: public
link (line 98)

Assigns a link filter for a single link, overwriting any existing link filters. clicks on the given link.

Assigns a link filter for a single link, overwriting any existing link filters. The result will only contain clicks on the given link. Invalid link IDs will be ignored.

  • return: this query.
  • access: public
Inx_Api_DataAccess_ClickDataQuery link (int $iLinkId)
  • int $iLinkId: the ID of the link by which the result shall be filtered.
links (line 108)

Assigns a link filter for several links, overwriting any existing link filters. clicks on the given links.

Assigns a link filter for several links, overwriting any existing link filters. The result will only contain clicks on the given links. Invalid link IDs will be ignored.

  • return: this query.
  • access: public
Inx_Api_DataAccess_ClickDataQuery links ( $aLinkIds)
  • array $aLinkIds: the IDs of the links by which the result shall be filtered.
linkType (line 140)

Assigns a link type filter for a single link type, overwriting any existing link type filters. only contain clicks on links of the given type.

Assigns a link type filter for a single link type, overwriting any existing link type filters. The result will only contain clicks on links of the given type. Invalid link types will raise an Inx_Api_IllegalArgumentException.

  • return: this query.
  • throws: Inx_Api_IllegalArgumentException if the given link type is not one of the link types specified in Inx_Api_DataAccess_LinkDataRowSet, excluding LINK_TYPE_UNKNOWN.
  • access: public
Inx_Api_DataAccess_ClickDataQuery linkType (int $iLinkType)
  • int $iLinkType: the link type by which the result shall be filtered.
linkTypes (line 152)

Assigns a link type filter for several link types, overwriting any existing link type filters. only contain clicks on links of the given types.

Assigns a link type filter for several link types, overwriting any existing link type filters. The result will only contain clicks on links of the given types. Invalid link types will raise an Inx_Api_IllegalArgumentException.

  • return: this query.
  • throws: Inx_Api_IllegalArgumentException if at least one of the given link types is not one of the link types specified in Inx_Api_DataAccess_LinkDataRowSet, excluding LINK_TYPE_UNKNOWN.
  • access: public
Inx_Api_DataAccess_ClickDataQuery linkTypes ( $aLinkTypes)
  • array $aLinkTypes: the link types by which the result shall be filtered.
mailing (line 78)

Assigns a mailing filter for a single mailing, overwriting any existing mailing filters. contain clicks on links which are part of the given mailing.

Assigns a mailing filter for a single mailing, overwriting any existing mailing filters. The result will only contain clicks on links which are part of the given mailing. Invalid mailing IDs will be ignored.

  • return: this query.
  • access: public
Inx_Api_DataAccess_ClickDataQuery mailing (int $iMailingId)
  • int $iMailingId: the ID of the mailing by which the result shall be filtered.
mailings (line 88)

Assigns a mailing filter for several mailings, overwriting any existing mailing filters. contain clicks on links which are part of the given mailings.

Assigns a mailing filter for several mailings, overwriting any existing mailing filters. The result will only contain clicks on links which are part of the given mailings. Invalid mailing IDs will be ignored.

  • return: this query.
  • access: public
Inx_Api_DataAccess_ClickDataQuery mailings ( $aMailingIds)
  • array $aMailingIds: the IDs of the mailings by which the result shall be filtered.
recipient (line 118)

Assigns a recipient filter for a single recipient, overwriting any existing recipient filters. only contain clicks performed by the given recipient.

Assigns a recipient filter for a single recipient, overwriting any existing recipient filters. The result will only contain clicks performed by the given recipient. Invalid recipient IDs will be ignored.

  • return: this query.
  • access: public
Inx_Api_DataAccess_ClickDataQuery recipient (int $iRecipientId)
  • int $iRecipientId: the ID of the recipient by which the result shall be filtered.
recipients (line 128)

Assigns a recipient filter for several recipients, overwriting any existing recipient filters. only contain clicks performed by the given recipients.

Assigns a recipient filter for several recipients, overwriting any existing recipient filters. The result will only contain clicks performed by the given recipients. Invalid recipient IDs will be ignored.

  • return: this query.
  • access: public
Inx_Api_DataAccess_ClickDataQuery recipients ( $aRecipientIds)
  • array $aRecipientIds: the IDs of the recipients by which the result shall be filtered.
sending (line 161)

Assigns a sending ID filter for a single sending ID, overwriting any existing sending ID filters. only contain clicks associated with this sending.

Assigns a sending ID filter for a single sending ID, overwriting any existing sending ID filters. The result will only contain clicks associated with this sending.

  • return: this query.
  • access: public
Inx_Api_DataAccess_ClickDataQuery sending (int $iSendingId)
  • int $iSendingId: the sending ID by which the result shall be filtered.
sendings (line 170)

Assigns a sending ID filter for several sending IDs, overwriting any exsiting sending ID filters. contain only clicks associated with these sendings.

Assigns a sending ID filter for several sending IDs, overwriting any exsiting sending ID filters. The result will contain only clicks associated with these sendings.

  • return: this query.
  • access: public
Inx_Api_DataAccess_ClickDataQuery sendings ( $aSendingIds)
  • array $aSendingIds: the sending IDs by which the result shall be filtered.

Documentation generated on Thu, 17 Sep 2015 14:27:22 +0200 by phpDocumentor 1.3.2