Follow the guide to associate your app with the Windows Store and with the Catapush Backend
If your app is Windows 10 UWP:
If your app is Windows Phone 8.1 RT:
If your app is Windows Phone 8.1 Silverlight:
Override the method OnActivated in App.xaml.cs and call CompletePickFile in CatapushUtils:
protected override void OnActivated(IActivatedEventArgs args)
{
base.OnActivated(args);
CatapushUtils.CompletePickFile(args);
}
Into Application_ContractActivated in App.xaml.cs call CompletePickFile in CatapushUtils:
private void Application_ContractActivated(object sender, Windows.ApplicationModel.Activation.IActivatedEventArgs e)
{
CatapushUtils.CompletePickFile(e);
}
We offer different level of use of our SDK: from what entirely automatic, with a few lines of code, to the most advanced. Lifte according to your needs.
Go to App.xaml.cs and inside the constructor ( public App() ) insert the Catapush initialization code:
Catapush.Instance.Init("YOUR_APP_KEY_FROM_CATAPUSH_DASHBOARD");
The easier way to use Catapush is instantiating the CatapushMessagesListView. It will do everything automatically after that all the properties will be settled.
In your XAML Page add:
- in Windows Phone 8.1 Silverlight
xmlns:catapush="clr-namespace:CatapushSDK.Controls;assembly=CatapushSDK.SL"
-in Windows Phone 8.1 RT and Universal Windows Platform:
xmlns:catapush="using:CatapushSDK.Controls"
And
<catapush:CatapushMessagesListView
Name="CatapushMessagesLV"
OnError="CatapushMessagesLV_OnError"
Username="CATAPUSH_USER"
Password="CATAPUSH_PASSWORD"
PushReceiverBackgroundTaskTypeFullName="CatapushSDK.Background.CatapushBackgroundTask"
PushChannelRefreshBackgroundTaskTypeFullName="CatapushSDK.Background.RefreshPushChannelBackgroundTask" />
In C# code will be present only the event handler:
private void CatapushMessagesLV_OnError(object sender, ErrorEventArgs e)
{
Debugger.Break();
}
Obviously you can set all the properties of CatapushMessagesListView also from C# code. When all these properties are assigned the CatapushMessagesListView automatically starts to show and receive messages.
If you want more control you can use the singleton Catapush.Instance to interact with the SDK.
Declare a ListView (ListBox for Silverlight) in XAML and define the ItemTemplate using our CatapushMessageControl (or your own, if you prefer). For example:
<ListView Name="CatapushMessagesLV" SelectionMode="None">
<ListView.ItemTemplate>
<DataTemplate>
<catapush:CatapushMessageControl />
</DataTemplate>
</ListView.ItemTemplate>
<ListView.ItemContainerStyle>
<Style TargetType="ListViewItem">
<Setter Property="Padding" Value="9" />
<Setter Property="HorizontalContentAlignment" Value="Stretch" />
</Style>
</ListView.ItemContainerStyle>
</ListView>
Remember to add this at the top of the XAML page if you are using our CatapushMessageControl:
- in Windows Phone 8.1 Silverlight
xmlns:catapush="clr-namespace:CatapushSDK.Controls;assembly=CatapushSDK.SL"
-in Windows Phone 8.1 RT and Universal Windows Platform:
xmlns:catapush="using:CatapushSDK.Controls"
Go to your C# page code and write something like this:
using CatapushSDK.EventsArgs;
using CatapushSDK.Model;
using System;
using System.Collections.ObjectModel;
using System.Diagnostics;
using System.Threading.Tasks;
using Windows.UI.Xaml.Controls;
using Windows.UI.Xaml.Navigation;
namespace CatapushSDK.RT.Demo
{
public sealed partial class MainPage : Page
{
private ObservableCollection<CatapushMessage> Messages;
public MainPage()
{
this.InitializeComponent();
this.NavigationCacheMode = NavigationCacheMode.Required;
Catapush.Instance.OnMessageReceived += Instance_OnMessageReceived;
Catapush.Instance.OnError += Instance_OnError;
}
protected async override void OnNavigatedTo(NavigationEventArgs e)
{
base.OnNavigatedTo(e);
try
{
if (!Catapush.Instance.IsRunning)
{
//get the old received messages
var dbMessages = await Catapush.Instance.GetMessagesAsync();
//create the messages list and set it as ItemsSource of the ListView
Messages = new ObservableCollection<CatapushMessage>(dbMessages);
CatapushMessagesLV.ItemsSource = Messages;
//start the CatapushSDK
await Catapush.Instance.StartAsync("CATAPUSH_USER",
"CATAPUSH_PASSWORD",
"CatapushSDK.Background.CatapushBackgroundTask",
"CatapushSDK.Background.RefreshPushChannelBackgroundTask");
//confirm the pending open if exists
var notOpenedConfirmed = dbMessages.Where(m => m.State == MessageStatus.ReceivedConfirmed ||
m.State == MessageStatus.Opened);
foreach (var message in notOpenedConfirmed)
await Catapush.Instance.NotifyOpenedAsync(message);
}
}
catch { Debugger.Break(); }
}
private async void Instance_OnMessageReceived(object sender, MessageEventArgs e)
{
try
{
await Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, async () =>
{
Messages.Add(e.Message);
await Task.Delay(500);
CatapushMessagesLV.ScrollIntoView(e.Message);
});
await Catapush.Instance.NotifyOpenedAsync(e.Message);
}
catch
{
Debugger.Break();
}
}
private void Instance_OnError(object sender, ErrorEventArgs e)
{
Debugger.Break();
//TODO something
}
}
}
Go to your App.xaml.cs and write an app suspension handler like this:
- RT and UWP:
private async void OnSuspending(object sender, SuspendingEventArgs e)
{
var deferral = e.SuspendingOperation.GetDeferral();
if (Catapush.Instance.IsRunning)
Catapush.Instance.Suspend();
// TODO: Save application state and stop any background activity
deferral.Complete();
}
- Silverlight:
private async void Application_Deactivated(object sender, DeactivatedEventArgs e)
{
if (Catapush.Instance.IsRunning)
Catapush.Instance.Suspend();
}
private async void Application_Closing(object sender, ClosingEventArgs e)
{
if (Catapush.Instance.IsRunning)
await Catapush.Instance.Suspend();
}
If you want to write your own background tasks, instead of our “CatapushSDK.Background.CatapushBackgroundTask” and “CatapushSDK.Background.RefreshPushChannelBackgroundTask”, you can do it writing a class like these inside your background task project:
public sealed class YourCatapushBackgroundTask : IBackgroundTask
{
public async void Run(IBackgroundTaskInstance taskInstance)
{
var deferral = taskInstance.GetDeferral();
try
{
Catapush.Instance.InitBackground();
await Catapush.Instance.StartBackgroundAsync(); //the Catapush messages are received and showed with toast and/or tile
}
catch { }
//TODO add here your code
deferral.Complete();
}
}
public sealed class YourRefreshPushChannelBackgroundTask : IBackgroundTask
{
public async void Run(IBackgroundTaskInstance taskInstance)
{
var deferral = taskInstance.GetDeferral();
try
{
await Catapush.Instance.RefreshPushChannelAsync();
}
catch { }
//TODO add here your code
deferral.Complete();
}
}
To enable/disable the toast notifications you can simply set this (default true):
Catapush.Instance.ShowToastNotification
To enable/disable the tile notifications you can simply set this (default true):
Catapush.Instance.ShowTileNotification
To enable/disable the badge notifications you can simply set this (default false):
Catapush.Instance.ShowBadgeNotification
Remember that if you want the badge working in lock screen (and not only on the tile) you must enable "Lock screen notifications" in the Package.appxmanifest
If you want to hide the notifications when the app is in foreground you can disable/enable them as in the following example:
public App()
{
UnhandledException += App_UnhandledException;
...
}
protected override void OnLaunched(LaunchActivatedEventArgs e)
{
Window.Current.VisibilityChanged += Current_VisibilityChanged;
...
}
private void Current_VisibilityChanged(object sender, Windows.UI.Core.VisibilityChangedEventArgs e)
{
Catapush.Instance.HideAnyNotifications = e.Visible;
}
private void App_UnhandledException(object sender, UnhandledExceptionEventArgs e)
{
Catapush.Instance.HideAnyNotifications = false;
...
}
If you decide to use our SDK UI components you can customize their appearance.
This is an example of customization of the CatapushMessageControl, in which Background and MessageForeground are changed from the default values.
<catapush:CatapushMessageControl
Background="#50BFF7"
MessageForeground="Black"
...
/>
In the table below the full list of the customizable properties.
It offers also an event OnAttachmentClicked that is fired when the attachment is clicked.
If you use our CatapushMessagesListView you can customize the message appearance simply by applying a Style (because a CatapushMessageControl is used as DataTemplate).
<catapush:CatapushMessagesListView
[...]
>
<catapush:CatapushMessagesListView.Resources>
<Style TargetType="catapush:CatapushMessageControl">
<Setter Property="Background" Value="#50BFF7" />
<Setter Property="MessageForeground" Value="Black" />
[...]
</Style>
</catapush:CatapushMessagesListView.Resources>
</catapush:CatapushMessagesListView>Obviously the properties are those of the CatapushMessageControl, described in the table below.
It offers also an event OnAttachmentClicked that is fired when the attachment is clicked.
| Property Name | Default Value |
|---|---|
| Margin | 0 |
| Background |
System Accent Color UWP: WP8.1 RT: WP8.1 SL: |
| MessageMargin | 12, 12, 12, 4 |
| MessageFontSize | 16 |
| MessageHorizontalAlignment | Left |
| MessageFontStyle | Normal |
| MessageFontWeight | Normal |
| MessageForeground | White |
| MessageTextWrapping | Wrap |
| DateTimeMargin | 12, 4, 12, 12 |
| DateTimeFontSize | 12 |
| DateTimeHorizontalAlignment | Right |
| DateTimeFontStyle | Normal |
| DateTimeFontWeight | Normal |
| DateTimeForeground | White |
| AttachedFlyout | null |
| ThumbMargin | 12, 12, 12, 4 |
If you want to show a flyout menu when the user is holding (long press) on a CatapushMessageControl you can use the AttachedFlyout property, like in the examples below.
<catapush:CatapushMessageControl><catapush:CatapushMessageControl.AttachedFlyout><MenuFlyout>
<MenuFlyoutItem Text="forward" Click="ForwardFlyoutItem_Click" />
<MenuFlyoutItem Text="delete" Click="DeleteFlyoutItem_Click" />
</MenuFlyout>
</catapush:CatapushMessageControl.AttachedFlyout>
</catapush:CatapushMessageControl>
<catapush:CatapushMessagesListView
[...]
>
<catapush:CatapushMessagesListView.Resources>
<Style TargetType="catapush:CatapushMessageControl">
<Setter Property="AttachedFlyout">
<Setter.Value>
<MenuFlyout>
<MenuFlyoutItem Text="forward" Click="ForwardFlyoutItem_Click" />
<MenuFlyoutItem Text="delete" Click="DeleteFlyoutItem_Click" />
</MenuFlyout>
</Setter.Value>
</Setter>
[...]
</Style>
</catapush:CatapushMessagesListView.Resources>
</catapush:CatapushMessagesListView>
Catapush provides the possibility to let your users sent you messages.
Just add a CatapushSendMessageControl to your XAML, like this:
<catapush:CatapushSendMessageControl
Username="CATAPUSH_USER"
Password="CATAPUSH_PASSWORD"
PushReceiverBackgroundTaskTypeFullName="CatapushSDK.Background.CatapushBackgroundTask"
PushChannelRefreshBackgroundTaskTypeFullName="CatapushSDK.Background.RefreshPushChannelBackgroundTask"
OnError="CatapushSendMessageControl_OnError" />
Properties Username, Password, PushReceiverBackgroundTaskTypeFullName and PushChannelRefreshBackgroundTaskTypeFullName are exactly equivalent to the ones of CatapushMessagesListView. If you want to use the CatapushSendMessageControl together with a CatapushMessagesListView, specify values for those properties just one time (we suggest in CatapushMessagesListView): that will be enough.
If you are using the SDK for Windows Phone 8.1 (both RT and Silverlight) you need :
<catapush:CatapushSendMessageControl
Username="CATAPUSH_USER"
Password="CATAPUSH_PASSWORD"
PushReceiverBackgroundTaskTypeFullName="CatapushSDK.Background.CatapushBackgroundTask"
PushChannelRefreshBackgroundTaskTypeFullName="CatapushSDK.Background.RefreshPushChannelBackgroundTask"
OnError="CatapushSendMessageControl_OnError" />
Deprecated: note that OnMessageSendSuccess and OnMessageSendFailure events of CatapushSendMessageControl are deprecated. Use instead OnMessageSendStart, OnMessageSendSuccess and OnMessageSendFailure events in Catapush.Instance (not necessary if you use CatapushMessagesListView because it automatically handles them).
The CatapushSendMessageControl can be customized setting the properties PlaceholderText, BorderBrush, Background, Foreground, ButtonContent as follows:
<catapush:CatapushSendMessageControl [...]
PlaceholderText="Write a message"
BorderBrush="Red"
Background="Blue"
Foreground="Green">
<catapush:CatapushSendMessageControl.ButtonContent>
<TextBlock Text="Send" />
</catapush:CatapushSendMessageControl.ButtonContent>
<catapush:CatapushSendMessageControl.AttachButtonContent>
<TextBlock Text="Attach" />
</catapush:CatapushSendMessageControl.AttachButtonContent>
</catapush:CatapushSendMessageControl>
| Property Name | Default Value |
|---|---|
| PlaceholderText | "Write a message" |
| BorderBrush |
Black |
| Background | White |
| Foreground | Black |
| ButtonContent | A rectangle colored with the system accent color containing the system send icon (swiping message for Silverlight and WinRT, paper airplane for UWP) |
| AttachmentButtonContent | A rectangle colored with the system accent color containing the system attach icon (a paper clip) |
If you don't want to use our built-in CatapushSendMessageControl you can write your own experience using the public method SendMessage in Catapush.Instance that are described in the Documentation below.
You can subscribe to OnMessageSendStart, OnMessageSendSuccess and OnMessageSendFailure events in Catapush.Instance to offer a better "loading experience" for the transmission process.
If a CatapushMessage has an attachment the boolean "HasAttachment" is true. You can use the method GetAttachmentAsync of Catapush.Instance to obtain the CatapushAttachment object that describes the attachment entity.
If you are using the CatapushMessagesListView you can subscribe to the event OnAttachmentClicked that is fired when an attachment inside the list is clicked. If you use a custom ListView, with CatapushMessageControl as DataTemplate, you can subscribe to OnAttachmentClicked on CatapushMessageControl. You can look at our GitHub samplesfor a demonstration of how to handle it.
The CatapushUtils static class offers some statich methods that helps you to easly manage the attachments experience and are described in the table below.
| public static async Task<StorageFile> GetDownloadedAttachmentFileIfExistsAsync(CatapushAttachment attachment) |
If the attachment file was already download this method will provide you the correct StorageFile, that is stored inside the app local storage. It returns null if the file does not exists, and you have to call DownloadAttachmentFileAsync method to download the file. |
| public static async Task<StorageFile> DownloadAttachmentFileAsync(CatapushAttachment attachment) |
Download the attachment file from Catapush cloud and save it in the application local storage. Before calling this method you should always try to use the GetDownloadedAttachmentFileIfExistsAsync. Be careful with the exception AttachmentNotFoundException because the file are stored in our cloud storage only for a limited time. |
| public static async Task<StorageFile> PickFileAsync() |
Usefull if you want to customize the send attachment experience. This is the same method automatically called by the built-in CatapushSendMessageControl. In Windows Phone 8.1 (RT and SL) you must call CompletePickFile as described in "Enable your app to pick attachments". |
| public static bool CompletePickFile(IActivatedEventArgs args) |
It exists only for Windows Phone 8.1 (both RT and Silveright). You must call this as described in "Enable your app to pick attachments" if you are using PickFileAsync. |
All the public methods and properties of Catapush SDK are availble throught the singleton Catapush.Instance and we try to keep the count as small as possible, to have a very easy to use library.
Remember that you haven't to use them directly if you use our CatapushMessagesListView and/or CatapushSendMessageControl.
| public void Init(string appKey) | Initialize Catapush library when used in foreground app. You must use the appKey provided by the Catapush Dashboard |
| public void InitBackground() | Initialize Catapush library when user from background task. Will be automatically used the last appKey used with the foreground Init |
| public async Task StartAsync(string username, string password, string backgroundTaskType) |
Start Catapush from foreground app: N.B. in Windows Phone 8.1 RT and Windows 10 UWP exists also a more friendly signature with the last parameter Type backgroundTaskType |
| public async Task StartBackgroundAsync(ushort autoRetryOnConnectionError = 5) |
Start Catapush from background task: To have a very easy to use experience we implemented a configurable auto-retry on connection error. If you don't want it you can pass 0 as parameter. |
| public async Task<List<CatapushMessage>> GetMessagesAsync() | Get all previously received messages from the DB |
| public async Task<bool> ClearMessagesAsync() | Delete permanently all messages from DB |
| public async Task<bool> DeleteMessageAsync(string messageId) | Delete a single message from DB |
| public async Task<bool> NotifyOpenedAsync(... , CancellationToken ct) |
Notify one or more received messages as opened. You should call this method for the received message with Status = ReceivedConfirmed || Status == Opened Four signature are available for a more comfortable use: - string messagesId - CatapushMessage message - IEnumerable<string> messagesIds - IEnumerable<CatapushMessage> messages
|
| public async Task<SendMessageResult> SendMessageAsync(...) |
Send a message. Three signatures are available for a more comfortable use: - string message - StorageFile attachment - string message, StorageFile attachment
Default CancellationToken have 30 seconds timeout for text message and 5 minutes for attachment upload |
| public async Task<CatapushAttachment> GetAttachmentAsync(...) |
If a CatapushMessage object has the boolan "HasAttachment" set to true you can get the attachment details as CatapushAttachment object using this method. Two signatures are available for a more comfortable use: - string messageId - CatapushMessage message |
| public async Task Suspend() | Should be called when the app is closed or suspended: - Disconnect the foreground client - The user will continue to receive notifications in background |
| public async Task StopAsync() |
Stop Catapush permanently: BE CAREFUL: The user will no longer receive notifications both in foreground and background |
| bool IsRunning | You can use this to check if Catapush is initialized and started. You should look at this befeore to call Init and Start methods. |
| bool ShowToastNotification |
To decide if show a toast notification when a message is received in background. Default: true |
| bool ShowTileNotification |
To decide if show the notification in the app tile. Default: true |
| bool ShowBadgeNotification |
To decide if show the notification in the app badge (lock screen and/or tile). Default: false Remember that if you want the badge working in lock screen (and not only on the tile) you must enable "Lock screen notifications" in the Package.appxmanifest |
| bool HideAnyNotifications |
To hide any notifications. Usefull when the app is in foreground. Default: false Remember to reset this value to 'true' when the app is hidden, closed or crashed for an unhandled exception |
| string DateTimeFormat |
To change the default string format used in the CatapushMessage object to produce: FormattedSentTime, FormattedReceivedTime, FormattedReadTime Default: the datetimes are formatted in a short and user-friendly way, using the current device culture |
| IFormatProvider DateTimeFormatProvider |
To change the default format provider used in the CatapushMessage object to produce: FormattedSentTime, FormattedReceivedTime, FormattedReadTime Default: the datetimes are formatted in a short and user-friendly way, using the current device culture |
| OnConnecting | Fired when the SDK is trying to connect |
| OnConnected | Fired when the connection is successful |
| OnDisconnected |
Fired when the connection is dropped or closed
Note: the DisconnectionReason property can help you find out what caused the disconnection |
| OnMessageReceived |
Fired when a new message is received
|
| OnMessageOpened | Fired when a received message is opened (Status: OpenedConfirmed) |
| OnError | Fired when an error occurs, unrelated to a method call (for the methods error look at the well documented exceptions in their signatures) |
| OnMessageSendStart | Fired when a new send starts. The event args contains a PlaceholderMessage that can be used to show a loading placeholder in the list view. Remember that placeholder CatapushMessage are not stored in the database. |
| OnMessageSendSuccess |
Fired when the send operation is completed successfully. The event args contains the old PlaceholderMessage and the effectively sent Message. You can remove the PlaceholderMessage from the list and add the Message. |
| OnMessageSendFailure | Fired when the send operation fails. The event args contains the PlaceholderMessage that fails. |
CatapushMessage class represent the most important object inside the Catapush SDK.
| string Id | A unique identifier for this message (and the related attachment, if exists) |
| string Body |
The text of message (can be empty if the message contains only attachment) |
| string Sender |
|
| DateTime SentTime |
|
| DateTime ReceivedTime |
|
| DateTime ReadTime |
|
| MessageStatus State |
Indicates the state of the message: |
| bool Sent |
It indicates if this message was Sent by user (outgoing message) |
| bool HasAttachment | It indicates whether this message has an attachment |
| string AttachmentPreview | If the attachment supports preview (currently only for images) this value is filled with the thumb image encoded as Base64 string |
| string AttachmentPreviewUri |
If you don't want to manually handle the AttachmentPreview string Catapush SDK provides you this URI inside the CatapushMessage object. When you get AttachmentPreviewUri an asynchronous operations starts to create a thumb file and PropertyChanged was raised when AttachmentPreviewUri is ready (CatapushMessage implements INotifyPropertyChanged). This behavior is very usefull for Binding this property as Source of Image. |
| bool Sending |
True for placeholder messages that are sending |
| string FormattedSentTime |
SentTime formatted as described by Catapush.DateTimeFormat and Catapush.DateTimeFormatProvider |
| string FormattedReceivedTime |
ReceivedTime formatted as described by Catapush.DateTimeFormat and Catapush.DateTimeFormatProvider |
| string FormattedReadTime |
ReadTime formatted as described by Catapush.DateTimeFormat and Catapush.DateTimeFormatProvider |
You can use Catapush on each of your Windows 8.1 Apps or greater (Silverlight 8.1, WinRT 8.1 or UWP).
Catapush's library is about 500 KB, with minor variations depending on the specific platform. Remember that Silverlight apps uses both SL and RT SDK because the background task is a WINMD component based on WinRT.
We don't want to drain your batteries or consume your data. If you receive one notification per hour, Catapush will consume less than 1% of your battery and less than 1 MB per day. With no notifications, the usage is around 0%.
How about three? See the GitHub samples for Windows Phone Silverlight, Windows Phone 8.1 and Universal Windows Platform. And yes, you can use these as a starting point to build your own app!
Api & Docs Map
