Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/topsort/topsort.php
https://github.com/topsort/topsort.php
Last synced: 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/topsort/topsort.php
- Owner: Topsort
- License: mit
- Created: 2021-08-30T17:35:19.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-03T17:40:32.000Z (4 months ago)
- Last Synced: 2024-10-06T17:08:42.081Z (4 months ago)
- Language: PHP
- Size: 40 KB
- Stars: 2
- Watchers: 12
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# topsort.php
A PHP Software Development Kit for interacting with the `auctions` and `events`
endpoints in the Topsort ecosystem.
## Installation
The recommended way to install Topsort's SDK for PHP is with Composer. Composer
is a dependency management tool for PHP that allows you to declare the
dependencies your project needs and installs them into your project.
```json
{
"require": {
"topsort/sdk": "3.0.1"
}
}
```
Or with the command line:
```bash
composer require topsort/sdk
```
## How it works
All operations are driven by our [OpenAPI documentation](https://docs.topsort.com/reference/integration-overview),
so all methods maps directly to the API description.
## Usage: Running an auction
`Topsort\SDK\SDK::auction` requires three arguments:
- slots: An array describing the product slots that are being auctioned.
- products: An array, with the id's of the participating products.
- session: An array, describing the user on the current session.
```php
create_auction($slots, $products)->wait();
// => [
// "results" => [
// [
// "resultType" => "listings",
// "winners" => [
// [
// "rank" => 1,
// "type" => "product",
// "id" => "gDG0HV97ed2s",
// "resovedBidId" => "AKFU78"
// ]
// ]
// ]
// ]
//]
```
## Usage: Reporting click events
Tracks whenever a product, promoted or not, had a click.
`Topsort\SDK\SDK::report_click` requires one argument, an array with the following keys:
- entity: Required for unpromoted products. Must be the ID for the product that was clicked.
- resolvedBidId: Required for promoted products. Must be the ID for the auction the product won.
- placement: Optional. An array describing the placement of the product on the site.
- id: Optional. The marketplace's ID for the event. If present, it should be unique. Topsort may use this field to de-duplicate events.
- opaqueUserId: Optional. The marketplace's ID for the user. Defaults to a random UUID stored in a cookie.
- occurredAt: Optional. A DateTime, from when the click happened. Defaults to the current time.
```php
"/categories/shoes",
];
// Report the click
$topsort_client->report_click([
"placement" => $placement,
"resolvedBidId" => "AKFU78",
]);
```
## Usage: Reporting impression events
Tracks the product impressions on the site, and if any auction winners were
rendered on the site.
`Topsort\SDK\SDK::report_impressions` requires one argument, an array with the following keys:
- entity: Required for unpromoted products. Must be the ID for the product that was rendered.
- resolvedBidId: Required for promoted products. Must be the ID for the auction the product won.
- placement: Optional. An array describing the placement of the product on the site.
- id: Optional. The marketplace's ID for the event. If present, it should be unique. Topsort may use this field to de-duplicate events.
- opaqueUserId: Optional. The marketplace's ID for the user. Defaults to a random UUID stored in a cookie.
- occurredAt: Optional. A DateTime, from when the impression happened. Defaults to the current time.
```php
[
"path" => "/categories/shoes",
],
"resolvedBidId" => "AKFU78",
];
// Report the impressions
$topsort_client->report_impression($impression);
```
## Usage: Reporting purchases events
`Topsort\SDK\SDK::report_purchase` requires one argument, an array with the following keys:
- items: An array of product data.
- opaqueUserId: Optional. The marketplace's ID for the user. Defaults to a random UUID stored in a cookie.
- occurredAt: Optional. A DateTime, from when the purchase happened. Defaults to the current time.
```php
"gDG0HV97ed2s",
"quantity" => 2,
"unitPrice" => 10000,
]
];
// Report the purchase
$topsort_client->report_purchase([
"occurredAt" => new DateTime(),
"items" => $items,
]);
```