Get started
Quick start
From a key to a first push in about 15 minutes.
You will create keys, add a person, register a phone, send one push and read what happened to it.
Before you start#
You need:
- A Sapagan workspace and an owner login to the console. Sapagan creates the organisation and its first owner for you.
- A Firebase project for your app, with its service account file. See FCM and APNs credentials.
- A phone or browser that can receive push. The Flutter and web SDKs register one for you; this guide registers a token by hand so you can see each step.
In a development workspace, only people on the test list receive anything. Add yourself first under Settings, Setup, "Test people". See Quiet hours and caps.
1. Get your keys#
Open the console and go to Settings, Setup. The page lists the steps and has a "For your developer" part with your API base URL and the workspace id.
Create two keys:
| Key | Looks like | Where it lives |
|---|---|---|
| Server key | ktg_workspace_... | Your backend only. It can do everything the API allows. |
| App key | ktg_app_... | Inside your app or web page. It is public by nature. |
A key is shown once. Put it in your secret store at once. More in API keys.
export SAPAGAN_URL="https://api.example.com"
export SAPAGAN_KEY="ktg_workspace_..."const base = process.env.SAPAGAN_URL!;
const headers = {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
};// Apps use an app key, never the server key.
final config = SapaganConfig.fromKey(
apiHost: const String.fromEnvironment('SAPAGAN_API_HOST'),
key: const String.fromEnvironment('SAPAGAN_APP_KEY'), // ktg_app_...
);2. Identify a person#
A person is a profile with an external id: the id your own system uses for them. Send profiles, events and devices to POST /v1/batch.
curl -X POST "$SAPAGAN_URL/v1/batch" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": [
{ "type": "profile", "id": "user-42", "attributes": { "name": "Budi Santoso" } }
]
}'const res = await fetch(`${base}/v1/batch`, {
method: "POST",
headers,
body: JSON.stringify({
items: [{ type: "profile", id: "user-42", attributes: { name: "Budi Santoso" } }],
}),
});
console.log(await res.json()); // { results: [...], summary: { items: 1, ok: 1, errors: 0, ... } }await Sapagan.instance.identify('user-42', traits: {'name': 'Budi Santoso'});The answer has one result per item. An item that fails is reported at its index and does not stop the others.
3. Register a device#
A device is a push token tied to a person. Use the SDK in a real app (see Flutter and Web). From your backend, a device is one more batch item:
curl -X POST "$SAPAGAN_URL/v1/batch" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": [
{ "type": "device", "op": "upsert", "profileId": "user-42", "platform": "android", "token": "<FCM registration token>" }
]
}'await fetch(`${base}/v1/batch`, {
method: "POST",
headers,
body: JSON.stringify({
items: [{ type: "device", op: "upsert", profileId: "user-42", platform: "android", token: fcmToken }],
}),
});final token = await FirebaseMessaging.instance.getToken();
if (token != null) Sapagan.instance.registerDeviceToken(token);platform is android, ios or web. For a browser, the token is the FCM web token from your own Firebase project.
4. Send a first push#
Upload your Firebase service account first (Settings, Setup, Push credentials), or the send has nowhere to go. Then send one transactional message with POST /v1/send:
curl -X POST "$SAPAGAN_URL/v1/send" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: first-push-1" \
-d '{
"to": { "externalId": "user-42" },
"content": {
"title": "Halo Budi",
"body": "Ini push pertama dari Sapagan.",
"destination": { "kind": "app", "path": "/home" }
},
"channels": ["push"]
}'const res = await fetch(`${base}/v1/send`, {
method: "POST",
headers: { ...headers, "Idempotency-Key": "first-push-1" },
body: JSON.stringify({
to: { externalId: "user-42" },
content: {
title: "Halo Budi",
body: "Ini push pertama dari Sapagan.",
destination: { kind: "app", path: "/home" },
},
channels: ["push"],
}),
});
const message = await res.json(); // 202 { id, status: "pending", ... }The answer is 202 with the message id. The message is sent within a moment.
5. See the result#
Read the message and its deliveries with GET /v1/send/{id}, or open the console. Totals are at GET /v1/send/stats.
curl "$SAPAGAN_URL/v1/send/$MESSAGE_ID" -H "Authorization: Bearer $SAPAGAN_KEY"const status = await (await fetch(`${base}/v1/send/${message.id}`, { headers })).json();A status of dispatched means the push went to the provider. suppressed and failed come with a statusReason, for example not_allowlisted for a person who is not on the test list of a development workspace. The SDKs report delivered and opened back, so opens show in the console and in GET /v1/send/stats.
Next#
- Concepts explains what you just used.
- Webhooks and Transactional messages cover the next step for a backend.
- Errors and limits lists what can go wrong.