mirror of
https://fast.feibisi.com/https://github.com/parcelvoy/platform.git
synced 2025-08-28 11:46:02 +08:00
Improves documentation for API and clients (#142)
This commit is contained in:
Chris Anderson
GitHub
parent
7bd77345f3
commit
7b2b9db5d3
11 changed files with 359 additions and 9 deletions
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
"label": "Advanced",
|
||||
"position": 5,
|
||||
"collapsible": true
|
||||
"position": 6,
|
||||
"collapsible": false
|
||||
}
|
||||
|
||||
|
|
@ -4,10 +4,10 @@ Parcelvoy comes with a few different types of authentication out of the box:
|
|||
- SAML
|
||||
- OpenID
|
||||
|
||||
Whereas a lot of platforms will gate SSO as a luxury feature and charge extra for it (this is known as the ***SSO Tax***) we opted to go the opposite direction and lean in completely to SSO to make sure you understand that Parcelvoy takes your security seriously. SSO is not something that only Enterprise companies should have, but should be available at every level.
|
||||
Whereas a lot of platforms will gate SSO as a luxury feature and charge extra for it (this is known as the **SSO Tax**) we opted to go the opposite direction and lean in completely to SSO to make sure you understand that Parcelvoy takes your security seriously. SSO is not something that only Enterprise companies should have, but should be available at every level.
|
||||
|
||||
## Basic
|
||||
Right out of the gate Parcelvoy is setup to use a simple ***Basic*** auth that allows for a single user that can be set inside of the environment variables. This is a limited form of auth as it does not allow for multiple users and is largely meant for evaluation purposes.
|
||||
Right out of the gate Parcelvoy is setup to use a simple **Basic** auth that allows for a single user that can be set inside of the environment variables. This is a limited form of auth as it does not allow for multiple users and is largely meant for evaluation purposes.
|
||||
|
||||
To change the credentials for basic auth, modify the following environment variables and restart your Parcelvoy instance.
|
||||
```
|
||||
|
|
@ -17,7 +17,7 @@ AUTH_BASIC_PASSWORD=password
|
|||
|
||||
|
||||
## SAML
|
||||
***Instructions coming soon.***
|
||||
**Instructions coming soon.**
|
||||
|
||||
### Config
|
||||
| key | type | required |
|
||||
|
|
@ -30,7 +30,7 @@ AUTH_BASIC_PASSWORD=password
|
|||
| AUTH_SAML_IS_AUTHN_SIGNED | boolean | false |
|
||||
|
||||
## OpenID
|
||||
***Instructions coming soon.***
|
||||
**Instructions coming soon.**
|
||||
|
||||
### Config
|
||||
| key | type | required |
|
||||
|
|
@ -51,4 +51,4 @@ You can utilize either SAML or OpenID to connect to your Google Account. We'll b
|
|||
4. Enter an app name and select an optional logo
|
||||
5. The SSO URL ->
|
||||
|
||||
***Instructions coming soon.***
|
||||
**Instructions coming soon.**
|
||||
|
|
|
|||
6
docs/docs/clients/_category_.json
Normal file
6
docs/docs/clients/_category_.json
Normal file
|
|
@ -0,0 +1,6 @@
|
|||
{
|
||||
"label": "Clients",
|
||||
"position": 5,
|
||||
"collapsible": false
|
||||
}
|
||||
|
||||
3
docs/docs/clients/android.md
Normal file
3
docs/docs/clients/android.md
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
# Android
|
||||
|
||||
The Android SDK is coming soon. Until then, you can utilize our client API's to identify users and track events.
|
||||
167
docs/docs/clients/api.md
Normal file
167
docs/docs/clients/api.md
Normal file
|
|
@ -0,0 +1,167 @@
|
|||
# API
|
||||
|
||||
## Authentication
|
||||
Authentication to client endpoints is handled via public bearer API keys. These API keys allow for ingestion only of data and only on select endpoints. You can generate a new public key at any time in the portal and we recommend using a separate key per platform.
|
||||
|
||||
To authenticate requests, set the `Authorization` header to be `Bearer YOUR_KEY` where `YOUR_KEY` is the API key you generated.
|
||||
|
||||
#### Example
|
||||
```json
|
||||
{
|
||||
"Authorization": "Bearer pk_dbf68c87-e579-4dac-b083-77fed0294e67"
|
||||
}
|
||||
```
|
||||
|
||||
## Endpoints
|
||||
### Alias User
|
||||
Merge a previous identifier to the users new identifier. This action can only be performed once.
|
||||
|
||||
#### Endpoint
|
||||
`POST /client/alias`
|
||||
|
||||
#### Body
|
||||
- **anonymous_id** string
|
||||
- **external_id** string
|
||||
|
||||
#### Responses
|
||||
- **204** - Success
|
||||
- **422** - Validation error
|
||||
|
||||
#### Example
|
||||
```json
|
||||
Endpoint: POST /client/alias
|
||||
|
||||
Headers: {
|
||||
"Authorization": "Bearer pk_token_here"
|
||||
}
|
||||
|
||||
Body: {
|
||||
"anonymous_id": "ANONYMOUS_ID",
|
||||
"external_id": "EXTERNAL_ID"
|
||||
}
|
||||
```
|
||||
|
||||
<br />
|
||||
|
||||
### Identify User
|
||||
Create or update a user profile with associated traits.
|
||||
|
||||
#### Endpoint
|
||||
`POST /client/identify`
|
||||
|
||||
#### Body
|
||||
- **anonymous_id** string (optional)
|
||||
- **external_id** string
|
||||
- **email** string (optional)
|
||||
- **phone** string (optional)
|
||||
- **timezone** string (optional)
|
||||
- **locale** string (optional)
|
||||
- **data** object (optional)
|
||||
|
||||
#### Responses
|
||||
- **204** - Success
|
||||
- **422** - Validation error
|
||||
|
||||
#### Example
|
||||
```json
|
||||
Endpoint: POST /client/identify
|
||||
|
||||
Headers: {
|
||||
"Authorization": "Bearer pk_token_here"
|
||||
}
|
||||
|
||||
Body: {
|
||||
"external_id": "EXTERNAL_ID",
|
||||
"email": "test@test.com",
|
||||
"timezone": "America/Chicago",
|
||||
"locale": "en",
|
||||
"data": {
|
||||
"first_name": "John",
|
||||
"last_name": "Smith",
|
||||
"has_completed_onboarding": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<br />
|
||||
|
||||
### Register Device
|
||||
Ingest information about the users device including the push notification token used for sending push notifications.
|
||||
|
||||
#### Endpoint
|
||||
`POST /devices`
|
||||
|
||||
#### Body
|
||||
- **anonymous_id** string
|
||||
- **external_id** string
|
||||
- **device_id** string - A UUID or other identifier that can be used to identify this device across requests
|
||||
- **token** string - The push notification token for that device
|
||||
- **os** string
|
||||
- **model** string
|
||||
- **app_build** string - i.e. 465
|
||||
- **app_version** string - i.e. 1.2.4
|
||||
|
||||
#### Responses
|
||||
- **204** - Success
|
||||
- **422** - Validation error
|
||||
|
||||
#### Example
|
||||
```json
|
||||
Endpoint: POST /client/devices
|
||||
|
||||
Headers: {
|
||||
"Authorization": "Bearer pk_token_here"
|
||||
}
|
||||
|
||||
Body: {
|
||||
"external_id": "EXTERNAL_ID",
|
||||
"device_id": "5e356e66-03aa-4926-a322-d7f5c89049c1",
|
||||
"token": "45d2e0c7bbb649679723a96d92d0fa305e356e6603aa4926a322d7f5c89",
|
||||
"os": "iOS 16.3",
|
||||
"model": "iPhone15,2",
|
||||
"app_build": "465",
|
||||
"app_version": "1.2.4"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
<br />
|
||||
|
||||
### Post Event
|
||||
Track and event or interaction.
|
||||
|
||||
#### Endpoint
|
||||
`POST /events`
|
||||
|
||||
#### Body
|
||||
An array containing at least one object with the following parameters:
|
||||
|
||||
- **name** string (optional) - The name of the event
|
||||
- **anonymous_id** string
|
||||
- **external_id** string
|
||||
- **data** object (optional)
|
||||
|
||||
Either an anonymous or external ID is required in order to post an event.
|
||||
|
||||
#### Responses
|
||||
- **204** - Success
|
||||
- **422** - Validation error
|
||||
|
||||
#### Example
|
||||
```json
|
||||
Endpoint: POST /client/events
|
||||
|
||||
Headers: {
|
||||
"Authorization": "Bearer pk_token_here"
|
||||
}
|
||||
|
||||
Body: [{
|
||||
"external_id": "EXTERNAL_ID",
|
||||
"name": "Product Purchased",
|
||||
"data": {
|
||||
"product_id": 12345,
|
||||
"price": 49.99,
|
||||
"quantity": 4
|
||||
}
|
||||
}]
|
||||
```
|
||||
81
docs/docs/clients/ios.md
Normal file
81
docs/docs/clients/ios.md
Normal file
|
|
@ -0,0 +1,81 @@
|
|||
# iOS (Swift)
|
||||
|
||||
## Installation
|
||||
Installing the Parcelvoy iOS SDK will provide you with user identification, deeplink unwrapping and basic tracking functionality. The iOS SDK is available through common package managers (SPM & Cocoapods) or through manual installation.
|
||||
|
||||
### Version Information
|
||||
- The Parcelvoy iOS SDK supports
|
||||
- iOS 12.0+
|
||||
- Mac Catalyst 13.0+
|
||||
- Xcode 13.2.1 (13C100) or newer
|
||||
|
||||
### Swift Package Manager
|
||||
Go to File -> Swift Packages -> Add Package Dependency and enter:
|
||||
```https://github.com/parcelvoy/ios-sdk```
|
||||
|
||||
## Usage
|
||||
### Initialize
|
||||
Before using any methods, the library must be initialized with an API key and URL endpoint.
|
||||
|
||||
Start by importing the Parcelvoy SDK:
|
||||
```swift
|
||||
import Parcelvoy
|
||||
```
|
||||
|
||||
Then you can initialize the library:
|
||||
```swift
|
||||
Parcelvoy.initialize(apiKey: "API_KEY", urlEndpoint: "URL_ENDPOINT")
|
||||
```
|
||||
|
||||
### Identify
|
||||
You can handle the user identity of your users by using the `identify` method. This method works in combination either/or associate a given user to your internal user ID (`external_id`) or to associate attributes (traits) to the user. By default all events and traits are associated with an anonymous ID until a user is identified with an `external_id`. From that point moving forward, all updates to the user and events will be associated to your provider identifier.
|
||||
```swift
|
||||
Parcelvoy.shared.identify(id: "USER_ID", traits: [
|
||||
"first_name": "John",
|
||||
"last_name": "Doe"
|
||||
])
|
||||
```
|
||||
|
||||
### Events
|
||||
If you wnat to trigger journey and list updates off of things a user does within your app, you can pass up those events by using the `track` method.
|
||||
```swift
|
||||
Parcelvoy.shared.track(
|
||||
event: "Event Name",
|
||||
properties: [
|
||||
"Key": "Value"
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
### Register Device
|
||||
In order to send push notifications to a given device you need to register for notifications and then register the device with Parcelvoy. You can do so by using the `register(token: Data?)` method. If a user does not grant access to send notifications, you can also call this method without a token to register device characteristics.
|
||||
```swift
|
||||
Parcelvoy.shared.register(token: "APN_TOKEN_DATA")
|
||||
```
|
||||
|
||||
### Deeplink Navigation
|
||||
To allow for click tracking links in emails can be click-wrapped in a Parcelvoy url that then needs to be unwrapped for navigation purposes. For information on setting this up on your platform, please see our [deeplink documentation](https://docs.parcelvoy.com/advanced/deeplinking).
|
||||
|
||||
Parcelvoy includes a method which checks to see if a given URL is a Parcelvoy URL and if so, unwraps the url, triggers the unwrapped URL and calls the Parcelvoy API to register that the URL was executed.
|
||||
|
||||
To start using deeplinking in your app, add your Parcelvoy deployment URL as an Associated Domain to your app. To do so, navigate to Project -> Target -> Select your primary target -> Signing & Capabilities. From there, scroll down to Associated Domains and hit the plus button. Enter the domain in the format `applinks:YOURDOMAIN.com` i.e. `applinks:parcelvoy.com`.
|
||||
|
||||
Next, you'll need to update your apps code to support unwrapping the Parcelvoy URLs that open your app. To do so, use the `handle(universalLink: URL)` method. In your app delegate's `application(_:continue:restorationHandler:)` method, unwrap the URL and pass it to the handler:
|
||||
|
||||
```swift
|
||||
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
|
||||
|
||||
guard let url = userActivity.webpageURL else {
|
||||
return false
|
||||
}
|
||||
|
||||
return Parcelvoy.shared.handle(universalLink: url)
|
||||
}
|
||||
```
|
||||
|
||||
Parcelvoy links will now be automatically read and opened in your application.
|
||||
|
||||
## Example
|
||||
|
||||
Explore our [example project](/Example) which includes basic usage.
|
||||
|
||||
|
|
@ -52,6 +52,8 @@ const config = {
|
|||
],
|
||||
],
|
||||
|
||||
|
||||
|
||||
themeConfig:
|
||||
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
|
||||
({
|
||||
|
|
@ -78,6 +80,7 @@ const config = {
|
|||
prism: {
|
||||
theme: darkCodeTheme,
|
||||
darkTheme: darkCodeTheme,
|
||||
additionalLanguages: ['swift', 'json', 'kotlin'],
|
||||
},
|
||||
}),
|
||||
};
|
||||
|
|
|
|||
48
docs/package-lock.json
generated
48
docs/package-lock.json
generated
|
|
@ -13,6 +13,7 @@
|
|||
"@fontsource/inter": "^4.5.15",
|
||||
"@mdx-js/react": "^1.6.22",
|
||||
"clsx": "^1.2.1",
|
||||
"docusaurus-plugin-remote-content": "^3.1.0",
|
||||
"prism-react-renderer": "^1.3.5",
|
||||
"react": "^17.0.2",
|
||||
"react-dom": "^17.0.2"
|
||||
|
|
@ -5502,6 +5503,31 @@
|
|||
"node": ">=6"
|
||||
}
|
||||
},
|
||||
"node_modules/docusaurus-plugin-remote-content": {
|
||||
"version": "3.1.0",
|
||||
"resolved": "https://registry.npmjs.org/docusaurus-plugin-remote-content/-/docusaurus-plugin-remote-content-3.1.0.tgz",
|
||||
"integrity": "sha512-859WYmC75l9hRYa1f/2FNF+FLcKbkHCM/0dehN1Wl1fIuoFzEPf3tcWs4jcEobRHYnoMjyupqAhmu0q5j3JoIg==",
|
||||
"dependencies": {
|
||||
"axios": "^0.26.1",
|
||||
"picocolors": "^1.0.0",
|
||||
"pretty-ms": "^7.0.1",
|
||||
"rimraf": "^3.0.2"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=12"
|
||||
},
|
||||
"peerDependencies": {
|
||||
"@docusaurus/core": "2.x"
|
||||
}
|
||||
},
|
||||
"node_modules/docusaurus-plugin-remote-content/node_modules/axios": {
|
||||
"version": "0.26.1",
|
||||
"resolved": "https://registry.npmjs.org/axios/-/axios-0.26.1.tgz",
|
||||
"integrity": "sha512-fPwcX4EvnSHuInCMItEhAGnaSEXRBjtzh9fOtsE6E1G6p7vl7edEeZe11QHf18+6+9gR5PbKV/sGKNaD8YaMeA==",
|
||||
"dependencies": {
|
||||
"follow-redirects": "^1.14.8"
|
||||
}
|
||||
},
|
||||
"node_modules/dom-converter": {
|
||||
"version": "0.2.0",
|
||||
"resolved": "https://registry.npmjs.org/dom-converter/-/dom-converter-0.2.0.tgz",
|
||||
|
|
@ -8449,6 +8475,14 @@
|
|||
"url": "https://github.com/sponsors/sindresorhus"
|
||||
}
|
||||
},
|
||||
"node_modules/parse-ms": {
|
||||
"version": "2.1.0",
|
||||
"resolved": "https://registry.npmjs.org/parse-ms/-/parse-ms-2.1.0.tgz",
|
||||
"integrity": "sha512-kHt7kzLoS9VBZfUsiKjv43mr91ea+U05EyKkEtqp7vNbHxmaVuEqN7XxeEVnGrMtYOAxGrDElSi96K7EgO1zCA==",
|
||||
"engines": {
|
||||
"node": ">=6"
|
||||
}
|
||||
},
|
||||
"node_modules/parse-numeric-range": {
|
||||
"version": "1.3.0",
|
||||
"resolved": "https://registry.npmjs.org/parse-numeric-range/-/parse-numeric-range-1.3.0.tgz",
|
||||
|
|
@ -9231,6 +9265,20 @@
|
|||
"renderkid": "^3.0.0"
|
||||
}
|
||||
},
|
||||
"node_modules/pretty-ms": {
|
||||
"version": "7.0.1",
|
||||
"resolved": "https://registry.npmjs.org/pretty-ms/-/pretty-ms-7.0.1.tgz",
|
||||
"integrity": "sha512-973driJZvxiGOQ5ONsFhOF/DtzPMOMtgC11kCpUrPGMTgqp2q/1gwzCquocrN33is0VZ5GFHXZYMM9l6h67v2Q==",
|
||||
"dependencies": {
|
||||
"parse-ms": "^2.1.0"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=10"
|
||||
},
|
||||
"funding": {
|
||||
"url": "https://github.com/sponsors/sindresorhus"
|
||||
}
|
||||
},
|
||||
"node_modules/pretty-time": {
|
||||
"version": "1.1.0",
|
||||
"resolved": "https://registry.npmjs.org/pretty-time/-/pretty-time-1.1.0.tgz",
|
||||
|
|
|
|||
|
|
@ -20,6 +20,7 @@
|
|||
"@fontsource/inter": "^4.5.15",
|
||||
"@mdx-js/react": "^1.6.22",
|
||||
"clsx": "^1.2.1",
|
||||
"docusaurus-plugin-remote-content": "^3.1.0",
|
||||
"prism-react-renderer": "^1.3.5",
|
||||
"react": "^17.0.2",
|
||||
"react-dom": "^17.0.2"
|
||||
|
|
|
|||
|
|
@ -4,7 +4,8 @@
|
|||
gap: 20px;
|
||||
}
|
||||
|
||||
.card {
|
||||
.cards a.card {
|
||||
background: var(--color-background);
|
||||
display: flex;
|
||||
border-radius: 8px;
|
||||
border: 1px solid var(--color-grey);
|
||||
|
|
|
|||
|
|
@ -20,6 +20,7 @@
|
|||
|
||||
--color-background: var(--color-white);
|
||||
|
||||
--ifm-background-color: var(--color-background);
|
||||
--ifm-navbar-background-color: var(--color-white);
|
||||
--ifm-color-primary: var(--color-primary);
|
||||
--ifm-heading-color: var(--color-primary);
|
||||
|
|
@ -31,6 +32,10 @@
|
|||
--ifm-color-primary-lightest: #3cad6e;
|
||||
--ifm-code-font-size: 95%;
|
||||
--docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
|
||||
--ifm-line-height-base: 1.4;
|
||||
--ifm-leading-desktop: 1.0;
|
||||
|
||||
--color-footer: var(--color-primary);
|
||||
}
|
||||
|
||||
/* For readability concerns, you should choose a lighter palette in dark mode. */
|
||||
|
|
@ -52,6 +57,12 @@
|
|||
--ifm-color-primary-lighter: #32d8b4;
|
||||
--ifm-color-primary-lightest: #4fddbf;
|
||||
--docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
|
||||
|
||||
--color-footer: var(--color-grey-soft);
|
||||
}
|
||||
|
||||
html {
|
||||
background: var(--color-background);
|
||||
}
|
||||
|
||||
body {
|
||||
|
|
@ -163,5 +174,34 @@ h1, h2, h3, h4, h5, h6 {
|
|||
}
|
||||
|
||||
.footer {
|
||||
background: var(--color-primary);
|
||||
background: var(--color-footer);
|
||||
}
|
||||
|
||||
.markdown h1:first-child {
|
||||
--ifm-h1-font-size: 2.5rem;
|
||||
}
|
||||
|
||||
.markdown > h2 {
|
||||
--ifm-h2-font-size: 1.7rem;
|
||||
border-bottom: 1px solid var(--color-grey);
|
||||
padding-bottom: 10px;
|
||||
}
|
||||
|
||||
.markdown > h3 {
|
||||
--ifm-h3-font-size: 1.3rem;
|
||||
}
|
||||
|
||||
.markdown > h2, .markdown > h3 {
|
||||
margin-bottom: 10px;
|
||||
}
|
||||
|
||||
.markdown a.hash-link {
|
||||
color: var(--color-grey-hard);
|
||||
font-size: 80%;
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
.markdown a.hash-link:hover {
|
||||
color: var(--color-primary);
|
||||
/* text-decoration: underline; */
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue
