DigitalPUSH - Documentation

Last updated August 11th, 2019

Introduction

The documentation will explain the extent of DigitalPUSH's services and their usage. Please read this document thoroughly for a better understanding of how to use DigitalPUSH's and how our services will benefit you.

Basics

What are web push notifications?
Web push notifications are notifications that can be sent to a user via desktop web and mobile web. These are alert style messages that slide in at the top or bottom right hand corner of a desktop screen, depending on the operating system, or appear on a mobile device in a manner nearly identical to push notifications delivered from apps. Web push notifications are delivered on a user's desktop or mobile screen anytime they have their browser open - regardless of whether or not the user is on the website.

Who can use web push notifications?
Basically anyone that has a website.

Browser support

All major browsers support Web Push. Android devices may also receive Web Push notifications, in addition to notifications from apps.

Browser Windows PC macOS Android iPhone(iOS)
Chrome YES YES YES NO
Firefox YES YES YES NO
Safari NO YES N/A NO
Microsoft Edge YES N/A YES N/A
Opera YES YES YES NO
Yandex YES YES YES N/A
Samsung Internet Browser N/A N/A YES(4.0+) N/A
UC Browser NO N/A NO NO
Internet Explorer NO N/A N/A N/A
Note : Internet Explorer is no longer receiving updates. Microsoft has switched development to Edge.

Service usage

DigitalPUSH and it's platform ( digitalpush.org ) offers a completely free of charge web push notification service. DigitalPUSH imposes no restrictions, charges, usage limitations or serving costs to it's users.

DigitalPUSH, unlike other similar "free" services, does not restrict a maximum number of push subscribers before the webmaster is forced to pay. No, everything is... well, free.

Registration

The registration process is pretty self explanatory. You go to the registration page, you complete the form, and you're done. We do not impose any approval or verification for someone to start using our services.

Your account

Once you've completed the registration process you will be taken to your account dashboard which contains general information about your account and push subscribers such as:

  • Your account balance
  • The total number of subscribers
    • Number of new subscribers in the current day
    • A comparison as a progress bar between the number of new subscribers in the current day compared to the previous day
  • The total number of messages sent
    • The total number of messages delivered
    • A comparison as a progress bar between the total number of recipients and the total number of messages delivered. The difference between the two numbers is the amount of unsubscribed users.
  • The total number of clicks
    • The click through rate in percentages
    • A progress bar based on the click through rate
  • A pie chart that contains the distribution of your subscribers based on their browser
  • A global map that contains the distribution of your subscribers based on their country
  • A pie chart that contains the distribution of your subscribers based on their operating system
  • A bar chart that contains the last 7 days statistics for :
    • Subscriptions
    • Recipients
    • Messages delivered
    • Clicks

Adding a website

To add a new website to your DigitalPUSH account, while logged into your DigitalPUSH account, under the "Websites" section in the navigation, click the "New website" link.

Complete the form in the page with the required information as it follows:

  1. Domain name
    Enter the domain of your website only! No http:// or https:// or www.
    If you want to add DigitalPUSH on a subdomain you will have to add that subdomain separately.
    Wildcard subdomains are not accepted.
  2. Website category
    Select the category that suits your website best.
  3. Monetization
    Select whether you would like to enable the monetization feature for your website.

Press the "Add my website" button and you're all set. Once again there is no waiting time or approval required.


Integration

To integrate DigitalPUSH's services within your website, web application or project you will need to fetch the implementation code for your website. For that, while logged into your DigitalPUSH account, under the "Websites" section in the navigation, click the "Get code" link. You can also access this page from the "Websites" page by pressing the "Get code" button specific for the website you are trying to implement our services for.

The implementation code contains the following parameters :

  • Code key
    An unique key generated for your implementation code
  • Delay
    You can select the delay between the moment when the visitor lands on the page and the moment when the subscription message is displayed
  • Welcome message
    This message will be shown to your visitor when the subscription message is displayed
  • Custom variables 1 to 5
    DigitalPUSH allows you to have up to 5 custom variables for each individual subscriber. These custom variables can be used to store names, emails, IDs, or any type of segmentation you consider fit.

Once you are happy with the customization of your implementation code, click the "Generate code" button.

Copy / Paste the implementation code within your website's HTML code. For better results include the implementation code in all your pages.


Custom parameters

DigitalPUSH offers 5 custom variables that can be passed for each subscription.

To make use of these, enable each of the custom variables while preparing your implementation code.

These custom parameters will be saved for each individual subscriber and can be used to automatically personalize each push notification you send.


To better demonstrate the use of this feature let's assume a scenario:

You are developing a chat application and you want to notify each offline member when he received a new message.

For that you can use the custom parameters to personalize each notification sent and in your implementation code you have assigned the DGPcustom1 variable to save the username of your user and the DGPcustom2 to save his first name.
Your implementation code is looking something like this:

<!-- Begin DigitalPUSH code -->
<script>
var DGPkey = "generated_unique_key"; //mandatory
var DGPdelay = "0";
var DGPmessage = "Enable notifications be informed when you receive a message on myawesomechatapp.com";
var DGPcustom1 = "<?php echo $username; ?>";
var DGPcustom2 = "<?php echo $user_first_name; ?>";
</script>
<script type="text/javascript" src="//cdn.digitalpush.org/lib.js"></script>
<!-- End DigitalPUSH code -->


Each of the subscribed users will have their usernames and first names storred, and when you will send them a message you will be able to use {custom1} which will be replaced with their username and {custom2} which will be replaced with their first name.

These custom parameters can be used in both the title and the body of a web push. In our example if the web push title is "Hey {custom2}", the {custom2} parameter will be replaced with the first name of the subscriber. If the subscriber's first name is John, the title "Hey {custom2}" will be received as "Hey John".

Sending push notifications

To send push notifications to your subscribers, while logged into your DigitalPUSH account, under the "Push messages" section in the navigation, click the "New message" link.

As a DigitalPUSH member you can send 3 types of messages:

  • SEND TO ALL - You will send a web push to all the subscribers of a website you own
  • SEGMENTED - You can target specific countries, browsers and operating systems from the subscriber base of a website
  • SINGLE - Send to a specified subscriber ID

After selecting the type of push message you wish to send you need complete the form before deploying your new web push.

We will be explaining the fields and what they stand for as it follows:

  • Website
    The website / property you are sending the web push for.

  • Load from template
    This option allows you to load the notification title, message, URL and icon from a previously saved template.

    To manage your saved templates, go to your "Sent messages" and expand the messages that were saved as a template to remove them or add new ones.

  • Notification title

    Required. The title of your web push. Maximum 64 characters allowed.
    The notification title allows the usage of {custom1} {custom2} {custom3} {custom4} {custom5} which will be replaced with the saved data from each subscriber as explained in the Custom parameters section.

  • Notification message

    Required. The body or content of your web push. Maximum 512 characters allowed.
    The notification message allows the usage of {custom1} {custom2} {custom3} {custom4} {custom5} which will be replaced with the saved data from each subscriber as explained in the Custom parameters section.

    Note. Different browsers will display different length of the notification body.

  • Notification URL
    Optional. The URL to which the subscriber will be redirected if he clicks the notification.
    Must include the http:// or https:// part.

  • Notification icon
    Optional. The icon of your web push.


    The notification icon has 3 selectable options :
    • No icon you will send a web push with no icon
    • Used previously use a notification icon from a previously sent web push
    • Upload an icon upload a new icon for this web push

  • Delivery
    This option allows you to select when will your campaign be delivered, and in here you have two other options :
    • Send immediately - The message will be delivered within the next 15 seconds.
    • Scheduled delivery - You can schedule your message to be delivered at a time of your choice.

  • Time to live
    ( seconds ) This option specifies how long will it take before the notification expires if the device is offline. The default is 259,200 ( 3 days ).

  • Subscriber ID *
    Enter the ID of the subscriber you wish to send the web push to. This ID can be fetched from the "Subscribers" section

    * Note This option is only available for the messages that have the type SINGLE, and is mandatory for this type of message.

  • Countries *
    Select whether you want to filter the subscribers receiving this message by country
    • Worldwide - Subscribers will not be filtered by country
    • Geotargeted - Subscribers will be filtered by country.
      Two new select boxes will appear, the select box in the right contains the countries that are allowed to receive the web push.

    * Note This option is only available for the messages that have the type SEGMENTED.

  • Browsers
    Select whether you want to filter the subscribers that the web push is being sent to based on browsers.
    • All browsers - Subscribers will not be filtered by browser
    • Selected browsers - Subscribers will be filtered by browser.
      A new multi-select box will appear and you can select which browsers you want to send to.

    * Note This option is only available for the messages that have the type SEGMENTED.

  • Operating systems
    Select whether you want to filter the subscribers that the web push is being sent to based on operating systems.
    • All operating systems - Subscribers will not be filtered by operating system
    • Selected operating systems - Subscribers will be filtered by operating system.
      A new multi-select box will appear and you can select which operating systems you want to send to.

    * Note This option is only available for the messages that have the type SEGMENTED.

Information after being deployed all messages are stored in our database and sent automatically by a cron job that runs every 15 seconds. We are mentioning this for our users to fully understand how the system works and why messages receive the "Pending" status after being deployed, as well as the small delay between the deployment of the message and the time being sent.

Monetization

Aside from our main service of allowing members to use web push notifications on their websites, DigitalPUSH enables it's users to monetize their subscribers.

The monetization process is pretty straightforward and 100% passive. Basically, all you need to do is to enable the monetization feature for one of your websites and you are pretty much done.

Application

To apply for the monetization feature for one of your websites:

  1. Select the "Enabled" value for the "Monetization" feature when adding your website.

  2. Or, while logged into your DigitalPUSH account, navigate to the "Websites" section and click on the "My websites" link. Click the green "Enable monetization" button that corresponds to the website you want to enable the monetization feature for.

Usage

Enabling the monetization feature for one of your websites means that you give DigitalPUSH the permission to send advertisements to the subscribers of that particular property.

Our system limits the number of advertisements shown per day per each subscriber to a maximum of 4.

DigitalPUSH shares up to 85% of the bid for a click / conversion / thousand views in favor of the member.

In some cases we will deny the monetization of websites that fit in certain categories mentioned within our Content policy

You can check your account balance under the "Financial" section or in your account dashboard.

Withdraws

Withdrawing your revenue with DigitalPUSH is as simple as it gets:

  1. While logged into your DigitalPUSH account, in the navigation menu, go to the "Financial" section, and click the "Withdraw funds" link.
  2. Complete the form and click the "Submit my withdraw" button and you are done.

The minimum withdraw amount via PayPal is $1.00 USD and $500.00 USD via wire transfer. Withdraw requests can be sent anytime. A withdraw request is usually processed within a couple of hours, however, in some cases ( weekends, national holidays ), it may take up to 48 hours to process a withdraw request.

To request a wire transfer withdraw please contact us.

Advertising

DigitalPUSH is not an ad network. DigitalPUSH is a service for the website owners. Not being a traffic hungry service that revolves solely around demand and supply enables our platform to provide the best possible traffic for any advertiser's campaigns.

Buying web push traffic directly from website owners and pin-point the traffic you buy will yield the highest R.O.I for any advertiser, regardless of the product, offer or campaign they are promoting.

Last but not least, the web push notifications are a new ad format that converts better than anything marketing has seen so far. Why? Because the traffic can't really be faked or generated. The clicks a campaign gets will always interest based.

Requirements

All campaigns submitted for approval must abide to our Content policy. In order to protect the subscribers of our members and due the high demand for ad format we tend to be very picky when it comes to approving campaigns.

DigitalPUSH does not limit the number of campaigns you can have. The only limitation we impose is a minimum of $0.10 USD per thousand views for CPM campaigns or $0.10 USD per click for CPC campaigns.

Note : We encourage advertisers to submit their campaigns for approval before actually depositing funds to their account.

Campaigns

On top of the features and segmentations that are similar to sending a web push ( see Sending push notifications ), advertisers get a few additional options to improve their targeting capabilities even further, such as:

  • Category targeting
    which will allow advertisers to target interest based traffic

  • Website targeting
    which enables advertisers to select exactly on which website(s) their campaign would appear

  • Website blocking
    which allows advertisers to stop displaying their campaign to underperforming websites if any

  • Country blocking
    which enables advertisers to target world-wide traffic minus countries they do not consider fit for their campaign

After submitting a campaign for approval please allow us between 2 and 48 hours to verify and approve it.


Notes

  1. Once approved the campaign content can not be changed. By content we refer to the notification title, body, icon and landing page URL.

  2. The audience targeting options can be modified on approved campaigns at any given time without altering the position of the campaign or it's bid.

  3. Approved campaigns will be deleted if they receive no traffic for more than 30 days.

Funding and deposits

Funding your account can be done automatically via PayPal. While logged into your DigitalPUSH account, in the main navigation, go to the "Financial" section and press the "Deposit funds" link. If you wish to deposit funds to your account via Wire Transfer or other payment methods please contact us.

The minimum amount you can deposit via PayPal is $10.00 USD


Your advertising campaigns will be live for as long as your account has funds. Approved campaigns with DigitalPUSH do not need to be funded separately.

Push API

DigitalPUSH offers an API interface that is used to integrate DigitalPUSH's distribution service capabilities with client's personal projects.

The push API is designed for developers and accompanied by a detailed documentation in the sections below.

Description

The DigitalPUSH Push API allows the DigitalPUSH members to integrate the web push service within their projects or web applications and distribute web push notifications to their subscriber base directly from their project or web application.

The push API is split in two sections, one for sending targeted single web pushes and the other for bulk sending.

API endpoint

All references to API requests in this document point to the root URL:
https://api.digitalpush.org/push/

Single notification API

To send a single notification through this API you will need to use an API key that has the "Single notification" type selected.

To generate a key for your website please follow these steps:

  1. Log into your DigitalPUSH account
  2. In the main navigation go to API
  3. Select the "Generate a new key" link
  4. Select the "API key website" to match the website you are generating the key for
  5. Select the "Single notification" as the "API key type"
  6. Press the "Generate my new key" button.

The single notification API accepts only POST requests. Cross-domain requests are not handled. The single notification API usage is limited to 1 request per second.


The API requires two headers to be passed through:

  1. Content-Type - will be set as application/json
  2. Authorization - will contain the generated key


Required request parameters :

Parameter Accepted values Information
subscriber_filter "id", "ip", "custom1", "custom2", "custom3", "custom4", "custom5" The filter by which the subscriber will be found
subscriber_value VARCHAR(64) The search value for the subscriber filter
message_title VARCHAR(64) The title of the web push notification
message_body VARCHAR(512) The body ( content ) of the web push notification
Optional request parameters :

Parameter Accepted values Information
message_time_to_live INT(6) How long will it take before the notification expires if the device is offline ( in seconds ). The default is 259,200 ( 3 days ).
message_click_url VARCHAR(128) The click URL of the web push
message_icon VARCHAR(128) The URL of the web push icon. https:// only images are accepted.

Example POST request :


POST https://api.digitalpush.org/push/ HTTP/1.1

Content-Type: application/json
Authorization: <key_goes_here>

{
	"subscriber_filter": "ip",
	"subscriber_value": "123.123.123.123",
	"message_title": "My web push title",
	"message_body": "The body of my web push notification",
	"message_click_url": "https://google.com",
	"message_icon": "https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png"
}


curl -X POST -H "Authorization: <key_goes_here>" -H "Content-Type: application/json" -d '{
	"subscriber_filter": "ip",
	"subscriber_value": "123.123.123.123",
	"message_title": "My web push title",
	"message_body": "The body of my web push notification",
	"message_click_url": "https://google.com",
	"message_icon": "https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png"
}' https://api.digitalpush.org/push/

Bulk sending API

To send a multiple notifications to the subscriber base of one of your websites, you will need to use an API key that has the "Bulk sending" type selected.

To generate a key for your website please follow these steps:

  1. Log into your DigitalPUSH account
  2. In the main navigation go to API
  3. Select the "Generate a new key" link
  4. Select the "API key website" to match the website you are generating the key for
  5. Select the "Bulk sending" as the "API key type"
  6. Press the "Generate my new key" button.

The bulk sending API accepts only POST requests. Cross-domain requests are not handled. The bulk sending API usage is limited to 1 request per minute.


The API requires two headers to be passed through:

  1. Content-Type - will be set as application/json
  2. Authorization - will contain the generated key


Required request parameters :

Parameter Accepted values Information
message_title VARCHAR(64) The title of the web push notification
message_body VARCHAR(512) The body ( content ) of the web push notification
Optional request parameters :

Parameter Accepted values Information
message_time_to_live INT(6) How long will it take before the notification expires if the device is offline ( in seconds ). The default is 259,200 ( 3 days ).
message_click_url VARCHAR(128) The click URL of the web push
message_icon VARCHAR(128) The URL of the web push icon. https:// only images are accepted.
segment_country VARCHAR(512) Country short code ( 2 letters ). Separated by ( ; )
segment_browser VARCHAR(64) Browser ID based on the list below. Separated by ( ; )
1 - Internet Explorer
2 - Mozilla Firefox
3 - Safari
4 - Google Chrome
5 - Opera
6 - Netscape
7 - Maxthon
8 - Konqueror
9 - Other
segment_os VARCHAR(64) Operating system ID based on the list below. Separated by ( ; )
1 - Windows
2 - Mac OS
3 - Linux
4 - Ubuntu
5 - iOS
6 - Android
7 - BlackBerry OS
8 - Other Mobile OS
9 - Other
segment_language VARCHAR(512) Language short code ( 2 letters ). Separated by ( ; )
segment_custom1 VARCHAR(1024) Segmentation by self registered custom variable. Separated by ( ; )
segment_custom2 VARCHAR(1024) Segmentation by self registered custom variable. Separated by ( ; )
segment_custom3 VARCHAR(1024) Segmentation by self registered custom variable. Separated by ( ; )
segment_custom4 VARCHAR(1024) Segmentation by self registered custom variable. Separated by ( ; )
segment_custom5 VARCHAR(1024) Segmentation by self registered custom variable. Separated by ( ; )

Example POST request :


POST https://api.digitalpush.org/push/ HTTP/1.1

Content-Type: application/json
Authorization: <key_goes_here>

{
	"message_title": "My web push title",
	"message_body": "The body of my web push notification",
	"message_click_url": "https://google.com",
	"message_icon": "https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png",
	"segment_country": "US;CA;AU",
	"segment_browser": "2;4;5",
	"segment_os": "1;2;6",
	"segment_language": "en;fr;es",
	"segment_custom1": "John;Mary;Jane",
	"segment_custom2": "Doe;Smith;Cena",
	"segment_custom3": "[email protected];[email protected];[email protected]",
	"segment_custom4": "Winter;Spring;Summer",
	"segment_custom5": "2002;1987;1991"
}


curl -X POST -H "Authorization: <key_goes_here>" -H "Content-Type: application/json" -d '{
	"message_title": "My web push title",
	"message_body": "The body of my web push notification",
	"message_click_url": "https://google.com",
	"message_icon": "https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png",
	"segment_country": "US;CA;AU",
	"segment_browser": "2;4;5",
	"segment_os": "1;2;6",
	"segment_language": "en;fr;es",
	"segment_custom1": "John;Mary;Jane",
	"segment_custom2": "Doe;Smith;Cena",
	"segment_custom3": "[email protected];[email protected];[email protected]",
	"segment_custom4": "Winter;Spring;Summer",
	"segment_custom5": "2002;1987;1991"
}' https://api.digitalpush.org/push/