Developers

Quick Start Guide: Send push notifications in 5 minutes

Roles in Pushed ecosystem

Pushed service targets different roles of users: subscribers (users that explicitly request getting push notfications) and creators (users that creates notifications). Creators, named in Pushed vocabulary as developers are the one responsible for the Push notifications sent to the clients using the different clients, iOs, Android and Website.

Workflow: Subscriptions, Apps & Channels

You do not need any coding skills to send push notifications, follow this simple steps to start sending notifications:

Request Developer Access

You do not need any coding skills to send push notifications, follow this simple steps to start sending notifications:

1. Register in Pushed by clicking here .
2. You will be redirected to a Request Developer Access page, if not, click here to request it. You must Agree the Terms and Privacy Policy.
3. You will receive shortly an email with an activation link. Please click the activation link to confirm your email address and enable your account to send push notifications. As part of the review process, we may be contacting you to verify the information you submitted.
4. Now you are ready to send notifications with Pushed. Access the control panel to set up a new application.
5. Open the Apps section in the top navigation bar.
6. Click on Create your first app now, you only have to set up a new name and a descriptionfor your app.
7. Once the app is created you will be redirected to the app settings page. By default, all new apps are private, it means that no one can subscribe unless it's invited (using the Members Only feature). If you want to make it public you just have to switch the Public toggle.
8. There are different ways to test and send your firsts notifications. Of course, to receive notifications first you have to subscribe to your recently created app, to do so you need the Pushed app (available for iOs and Android). We recommend using the mobile app download here , because you will be able to see how notifications and application works, but you can also use the site timeline to check them. Of course you can also start using our API, but that is one step further and requires coding skills, find here more information about using Pushed API.
9. To subscribe to your recently created app open the Pushed mobile app tap on the icon. This will open the search view, to make it simple, tap on the and scan the code provided in the app settings page . Once you have scanned the code, a confirmation message will appear saying that you have successfully subscribed to the application.
10. Now you are ready to send your first notification. Back on app settings page , click on Notifications and then New Notification. A modal window will appear asking for the notification details: content and target. If you followed this guide step by step, at this point you will only have one app created that will be preselected by default, so you only have to insert the notification content and click Send Notification. That's all! The notification will be queued and in a matter of seconds you will receive it in all your devices. Remember that you can download Pushed and set up your account in as many devices as you want.

Integrating Pushed

In order to build interesting services, push notification shipments must be done programatically. There is where Pushed is extremely useful. Integrations can be done in any third-party system, as Pushed works everywhere, because it does not depends on any library. OAuth2 is a protocol that lets external apps request authorization to private details in a user’s Pushed account without getting their password. This is preferred over Basic Authentication because tokens can be limited to specific types of data, and can be revoked by users at any time.

All developers need to register their application before getting started. A registered OAuth application is assigned a unique Client ID and Client Secret. The Client Secret should not be shared.

Pushed implements OAuth2 to allow external applications send notifications to users. The protocol request authorization to users so Pushed applications can send notifications directly without getting their password. Remember that users can subscribe to your applications without the need to implement OAuth. OAuth is only recommended for applications that needs to send different information to each user.

This is how the extended integration works:

1. Redirect users to request Pushed access: User has to authorize your application to send notifications directly. To do that you have to use the Authorization Link. In your process, you will have to redict the user to this site and add as a GET parameter the redirect URL you want Pushed retrieve the authorization data. You can find the Authorization Link in the settings page of your Pushed app. The Auhtorization Link will look like this:

   GET https://api.pushed.co/1/oauth/?client_id=APPKEY&state=pxyzABC123&redirect_uri=http://example.com/response

   Regarding the state value

   The primary reason for using the state parameter is to mitigate CSRF attacks by using a unique and non-guessable value associated with each authentication request about to be initiated. That value allows you to prevent the attack by confirming that the value coming from the response matches the one you sent.

   The state parameter is a string so you can encode any other information in it. You send a random value when starting an authentication request and validate the received value when processing the response. You store something on the client application side (in cookies, session, or localstorage) that allows you to perform the validation. If you receive a response with a state that doesn't match, you can infer that you may be the target of an attack because this is either a response for an unsolicited request or someone trying to forge the response.

   The state length can be up to 40 characters.

   And if you open the Authorization Link with a valid redirect URL as a parameter, you will find this view .

   This starts the OAuth 2.0 authorization flow. This isn't an API call, it's the web page that lets the user sign in to Pushed and authorize your app. After the user decides whether or not to authorize your app, they will be redirected to the URI specified by redirect_uri. You must specify the redirect_uri parameter to the authorization link so Pushed can callback the specified URI with authorization details response.

   The client_id corresponds to your app_key. You can find your app_key in the Settings section of your application in Pushed's Developer Portal.

   Note that each of your applications have its own and unique app_key.

   If you don't provide redirect_uri, state or client_id you will get an Invalid Authorization Link error.

   Additionaly, you can provide a name parameter that will be the name of your OAuth application or integration. This parameter must be an alphanumeric string, max 40 characters.

2. Pushed redirects back to your site: If the user accepts your request, Pushed redirects back to your site with a temporary access_token in a code parameter as well as the state you provided in the previous step in a state parameter. If the states don’t match, the request has been created by a third party and the process should be aborted.

   abcdefghijklmnopqrtuxwyz0123456789ABDCDE

   GET https://example.com/response?code=code

3. Exchange this for an access token: Now you must exchange the code parameter for an access_token using the oauth/access_token API endpoint.

   POST https://api.pushed.co/1/oauth/access_token

   This will be the response:

   {
     "response": {
       "type": "app_authorization_accepted",
       "message": "App has been granted access.",
     "data": {
       "access_token": "Gv3Rnmu0rBnrE56Ee18BV46CLrtu5mcGmML07GqU"
     }
   }

   You should also store the access_token given by Pushed in your system so you can send notifications at any time. Notice that the user can revoke at any time this permission, to verify if you have the right permissions you can use oauth/verify endpoint. The verification will give a response like this:

   {
     "response": {
       "type": "auth_code_valid",
       "message": "Authorization Code is valid."
     }
   }

4. And that is all! Now you are able to send to this user notifications at any time you want. To do that you have to use the push API endpoint and the access_token provided in previous step. Here you have an example:
   Sample Code: Command Line

   • Command Line
   • Perl
   • PHP
   • Ruby
   • Python

   Copy to clipboard

   curl -X POST -s \
     --form-string "app_key=your_app_key" \
     --form-string "app_secret=your_app_secret" \
     --form-string "target_type=your_target_type" \
     --form-string "content=Your notification content." \
     --form-string "access_token=access_token_code_given_by_pushed" \
     https://api.pushed.co/1/push

Targets

Depending on which target you want to reach for your notifications, you will have to specify the target_type parameter. This is the available target types:

Target Name	Description
app	Send a notification to all subscribers of an app.
channel	Send a notification to all subscribers of a channel.
user	Send a notification to an specific user specifying user alias. (OAuth required)
pushed_id	Send a notification to an specific user specifying Pushed ID.
email	Send a notification to an specific user using its email (registered in Pushed).

Webhooks

Webhooks allow you to build or set up integrations which subscribe to certain events on Pushed. When one of those events is triggered, we’ll send a HTTP POST payload to the webhook’s configured URL. Webhooks can be used to update an external database, trigger new notifications, or other actions. You’re only limited by your imagination. This is the current list of events available, if you need more, please contact us :

Name	Description
New Subscription	Any time a users subscribes to your app or channel.
Unsubscription	Any time a users unsubscribes from your app or channel.

Example of a webhook delivery:

POST /payload HTTP/1.1

Host: localhost:1234
X-Pushed-Delivery: 22
User-Agent: Pushed-Hookshot/A1FWxQ
Content-Type: application/x-www-form-urlencoded
Content-Length: 6615
X-Pushed-Event: new_subscription

{
  "user_alias": "opened",
  "alias": "gTMzWE",
  "subscription_alias": "KDCWDgE9gE"
  }
}

HTTP requests made to your webhook’s configured URL endpoint will contain several special headers:

Header	Description
X-Pushed-Event	Name of the event that triggered this delivery.
X-Pushed-Delivery	Unique ID for this delivery.

Also, the User-Agent for the requests will have the prefix Pushed-Hookshot/.

To setup new webhooks you only have to got the Webhooks section in your app profile in the Control Panel and specify a valid URL to post the data.

Shipments

Each time you send a push notification a Shipment is created. A shipment can be a group of notifications or a single notification. Shipments is the way that Pushed manages the sending, so you can track it globally. In the Control Panel , every one of your apps has a list of shipments where you can review the analytics of every shipment.

Notifications Policy

In order to optimize server resources, notifications will not be stored neither sent if there are not subscribers. That means that notifications sent to applications or channels with no subscribers will not be visible in the control panel.

Analytics

Pushed allows you to easily track your users engagement and acccess to who, when and how many times your notifications are being opened and shared. You can review this information in the shipments page of your Pushed app/channel.

Schedule Notifications

Each time you send a push notification a Shipment is created. A shipment can be a group of notifications or a single notification. Shipments is the way that Pushed manages the sending, so you can track it globally. In the Control Panel , every one of your apps has a list of shipments where you can review the analytics of every shipment. This is a premium feature, you will need a paid account to schedule notifications.

QR Subscription Code

Pushed offers out of the box QR Subscriptions Codes so you can embed and share it on your site. This way your audience can easily subscribe to your applications and channels incredibly fast. QR Subscription codes can be found on your app/channel settings page.

Rich Notifications

Pushed notifications allows multiple content options: attach links, images/videos that will be properly displayed on Pushed clients. At this time, rich content notifications are only allowed through API.