repo_zf1/documentation/manual/en/module_specs/Zend_Mobile_Push-C2dm.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.mobile.push.c2dm">
    <title>Zend_Mobile_Push_C2dm</title>

    <para>
        <classname>Zend_Mobile_Push_C2dm</classname> provides the ability to
        send push notifications to Android devices that contain Google Services. 
        A message will always be constructed with
        <classname>Zend_Mobile_Push_Message_C2dm</classname>.
    </para>

    <sect2 id="zend.mobile.push.c2dm.server">
        <title>Pushing Messages</title>

        <note>
            <para>Prior to pushing messages; you must
                <ulink
                    url="http://code.google.com/android/c2dm/signup.html"> sign
                    up for a c2dm account</ulink>.  In order to get your application
                    to recieve push notifications, you should follow: <ulink
                    url="http://code.google.com/android/c2dm/index.html#writing_apps">Writing
                    Android Applications that Use C2DM</ulink>.</para>
        </note>

        <para>
            When implementing C2DM; you have a few components that
            you will utilize.  <classname>Zend_Mobile_Push_C2dm</classname>
            which contains the server components and
            <classname>Zend_Mobile_Push_Message_C2dm</classname> which contains
            the message that you would like to send.  Each message sent must do
            an HTTP request; so remember this when sending in large batches.
        </para>

        <para>
            The actual implementation of the code is fairly minimal; however,
            considerations to error handling must be taken.
        </para>

        <programlisting language="php"><![CDATA[
try {
    $client = Zend_Gdata_ClientLogin::getHttpClient(
        'my@gmail.com', // REPLACE WITH YOUR GOOGLE ACCOUNT
        'myPassword', // REPLACE WITH YOUR PASSWORD
        Zend_Mobile_Push_C2dm::AUTH_SERVICE_NAME,
        null,
        'myAppName' // REPLACE WITH YOUR APP NAME
    );
} catch (Zend_Gdata_App_CaptchaRequiredException $cre) {
    // manual login is required
    echo 'URL of CAPTCHA image: ' . $cre->getCaptchaUrl() . PHP_EOL;
    echo 'Token ID: ' . $cre->getCaptchaToken() . PHP_EOL;
    exit(1);
} catch (Zend_Gdata_App_AuthException $ae) {
    echo 'Problem authenticating: ' . $ae->exception() . PHP_EOL;
    exit(1);
}

$message = new Zend_Mobile_Push_Message_C2dm();
$message->setId(time());
$message->setToken('ABCDEF0123456789');
$message->setData(array(
    'foo' => 'bar',
    'bar' => 'foo',
));

$c2dm = new Zend_Mobile_Push_C2dm();
$c2dm->setLoginToken($client->getClientLoginToken());

try {
    $c2dm->send($message);
} catch (Zend_Mobile_Push_Exception_InvalidToken $e) {
    // you would likely want to remove the token from being sent to again
    echo $e->getMessage();
} catch (Zend_Mobile_Push_Exception $e) {
    // all other exceptions only require action to be sent or implementation of exponential backoff.
    echo $e->getMessage();
}
]]></programlisting>

        <table id="zend.mobile.push.c2dm.server.exceptions">
            <title>Exceptions and Remediation Techniques</title>
            <tgroup cols="3" align="left" colsep="1" rowsep="1">
                <thead>
                    <row>
                        <entry>Exception</entry>
                        <entry>Meaning</entry>
                        <entry>Handling</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>Zend_Mobile_Push_Exception</entry>
                        <entry>These types of exceptions are more generic in nature
                        and are thrown either from C2DM when there was an unknown exception
                        or internally on input validation.</entry>
                        <entry>Read the message and determine remediation steps.</entry>
                    </row>
                    <row>
                        <entry>Zend_Mobile_Push_Exception_InvalidPayload</entry>
                        <entry>Generally the payload will not throw an exception
                        unless the size of the payload is too large or it is missing
                        required content.</entry>
                        <entry>Check the size of the payload is within the
                        requirements of C2DM</entry>
                    </row>
                    <row>
                        <entry>Zend_Mobile_Push_Exception_InvalidToken</entry>
                        <entry>Any form of an invalid token will be if the token is
                        no longer registered; you are missing a token or it is in an
                        invalid format.</entry>
                        <entry>You should remove the token and not attempt to send
                        to it again.</entry>
                    </row>
                    <row>
                        <entry>Zend_Mobile_Push_Exception_InvalidTopic</entry>
                        <entry>An invalid topic simply means that the message id was
                        too long or not an integer.</entry>
                        <entry>Ensure that the message ID is an integer.</entry>
                    </row>
                    <row>
                        <entry>Zend_Mobile_Push_Exception_DeviceQuotaExceeded</entry>
                        <entry>You have sent too many messages to this device;
                            you may retry again later.</entry>
                        <entry>Grab the HTTP client and check to see if there
                            was a retry-after header; otherwise implement
                            <ulink
                                url="http://en.wikipedia.org/wiki/Exponential_backoff">Exponential
                                Backoff</ulink></entry>
                    </row>
                    <row>
                        <entry>Zend_Mobile_Push_Exception_QuotaExceeded</entry>
                        <entry>You have sent too many messages and have gone
                            over the quota for the day; you may try again later.</entry>
                        <entry>Grab the HTTP client and check to see if there
                            was a retry-after header; like above implement
                            Exponential Backoff.  Secondly; if you are
                            continually going over your limit; you may request
                            <ulink
                                url="http://code.google.com/android/c2dm/quotas.html">Request
                            a higher quota</ulink>.  See the link on the bottom of
                            the page.</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
    </sect2>

    <sect2 id="zend.mobile.push.c2dm.message">

        <title>Advanced Messages</title>

        <para>
            C2DM provides the ability for sending more advanced messages; for
            instance the examples above show the most basic implementation of a
            message.  <classname>Zend_Mobile_Push_Message_C2dm</classname>
            allows you to do far more advanced messaging outlined below.
        </para>

        <sect3 id="zend.mobile.push.c2dm.message.delay-while-idle">

            <title>Delay While Idle</title>

            <para>
                If included, indicates that the message should not be sent
                immediately if the device is idle. The server will wait for the
                device to become active, and then only the last message for each
                collapse_key value will be sent.
            </para>

            <programlisting language="php"><![CDATA[
    $message = new Zend_Mobile_Push_Message_C2dm();
    $message->setDelayWhileIdle(true);
    ]]></programlisting>

        </sect3>
    </sect2>
</sect1>