Hackathon Workshop transcripts

Hey Pioneers! Below, the Pi Core Team is releasing transcripts for our #buildpi2gether Hackathon workshop videos on how different Pi resources can be utilized to build your project. Let us know if there’s anything we can do to make our content more accessible!

Hackathon Workshop video 1

Title: Pi Developer Portal Introduction

Video Script:

Hi everyone, I’m Lyriaaw from the Pi Core Team. In this introduction video, we will discuss and discover the new Pi Developer portal, released in July this year.. Along with Brainstorm, the developer portal is meant to be your main companion in your development journey with Pi Network.

From ideation to release, all the steps can be managed from these two utilities. Whereas Brainstorm is mostly meant for ideation, funding, and team gathering, the Developer Portal is oriented towards managing your Application in the PI Network Platform.

In this video, we will focus mostly on the Pi Developer Portal and its capabilities.

1 — CREATING AN APP

1.A — The basic fields

When you open the developer portal for the first time, you will see this utility presented. You can click the “New App” button to start the creation process. From here, you should now see the application creation form. App Name and Description are pretty self-explanatory. If you have a Brainstorm project associated with your app, you should use the same name. At the end of the form, you will be asked for your Github and Discord usernames. We may want to create a developers groups on discord and github, so we will start collecting usernames now. These two fields are 100% optional. In the future, we want to create a bridge between Brainstorm and the developer portal, so that the whole app lifecycle is seamless.

1.B — Self hosted / Hosted by pi core team

In the middle of the form, you will see a question asking if you want the app to be self hosted or hosted by Pi Core Team.

1.B.1 — Self hosted

Self Hosted means that you are the one handling your application on production. You can have your own infrastructure, but you are the one taking care of the scaling and the availability. If you select this option, you will be asked for the frontend URL of your application. As explained in previous videos, Pi Utilities are actually websites running in an iframe, therefore you must provide this url for the Pi Browser to be able to display your app.

1.B.1 — Hosted by Pi Core Team

On the other hand, Hosted by Pi Core Team means that we are taking care of your application — no infrastructure management, no availability issues, you simply take care of the code. Although the first option is available for everyone, the second requires you to pass the brainstorm developer test

As you all know, Pi Core Team is currently organising a hackathon. Upon joining the event and saying you are a developer, you will be sent to a technical test. When Brainstorm and the developer portal are connected, passing the technical test will automatically open the next steps for you.

Finally, when you select this action, instead of a frontend url, you will be asked for a gitlab username. This will be useful for us in order to provide you with a Gitlab project, already integrated with our deployment pipeline. You can now click the submit button and follow me to the next page.

2 — FRONTEND VALIDATION

If you choose to host your application yourself, you will need to verify your domain ownership. This is meant to avoid developers creating apps from websites they do not represent. For instance, you shouldn’t be able to impersonate the wikipedia.com domain name.

In order to prove your ownership over the domain name, you will need to place a specific file at the root of your domain. The content of the file must match the content of the text field in the gray box.

When you are done placing the file with the correct content at the root of your domain, you can click the “Verify domain” button. You will either see an error message with some debugging information, or the gray box should disappear and a green check mark should appear next to your domain url. Congratulations, your domain ownership is now verified, and you can access your app through the PI Browser by typing your app url in the address bar.

3 — API KEY

With the Pi SDK comes the Pi API, where you can execute HTTP requests against the main Pi Backend. For now this is only meant to handle payments but more abilities will be added in the future, like creating chat conversations on the Pi Chat from your application. At the bottom of the page, you can see a section called “API Keys”. You will need it to access the PI Backend as an application developer. Keep it safe! Anyone with this key can pretend to be you.

Note that accessing the public Pi blockchain does not require any API keys, you can simply produce transactions using your App’s private key and submit them directly to the blockchain through any public node (e.g. your own node, one of Pi Core Team’s nodes, or any other node that is running the “Blockchain API service”)

3 — SCOPES

Scopes is a feature that allows developers to request different levels of access to users. By default, apps only get access to an anonymised user identifier, but if it is essential for an app to know its users’ usernames (e.g. to display it in the interface) then it must request the “username” scope. If an app intends to request its users to make Pi payments to the app, then it must request the “payments” scope. The requests scopes are visible to the users, thus to maximize the number of people comfortably installing your app, we recommend only asking for the minimum number of scopes absolutely necessary for your app to function. You can always ask for more scopes later. Note that the scope facility is currently being actively developed by the core team.

Conclusion

With this new tool and the integration of brainstorm, you will be able to manage your application from an idea to its public release. Creating an app on a blockchain has never been easier than now. Feel free to try out the SDK and show us what you can add to the Pi utilities ecosystem.

Hackathon Workshop video 2

Title: Pi SDK & Sandbox introduction

Video Script:

My name is Hakkyung, and in this video, I’m going to present how to use Pi SDK and authenticate users, and how you can run your app in the sandbox environment for development purposes. Keep in mind that Pi apps are web apps that are loaded in the environment which enables them to interact with the resources offered by the Pi Apps Platform. For that purpose, you need to install a piece of Javascript called the client SDK in your app. Since Pi Apps are primarily web apps, you can debug them in the desktop browser using the sandbox environment.

We are going to use this simple single page application called Pi Online Bakery. It is initialized with create-react-app, but you can still create your demo app with barebone HTML and javascript.

To use Pi SDK, you need to add an SDK script tag to your frontend. Then you need to call the init function to initialize the SDK. You need to specify the version to ensure compatibility with future SDK releases. As of now, the version 2.0 is the latest so we put 2.0 here, and the sandbox flag to be true, which I’m going to talk about in a minute. This sandbox flag is optional and lets you configure the SDK to run in the sandbox. It’s handy if you control this variable with the environment variable, but to be explicit, I’m setting it to true here.

Let’s go to the developer portal. I’m assuming you have registered your app on the portal as I did here. To load your app in the sandbox, you need to set the “development URL”. Right now it says “Not configured” so let’s edit this. This will typically be localhost with a custom port which depends on your development environment. Here I’m using localhost with 3003 port. Once you set the development URL, a sandbox url is generated. Open this url in the desktop browser, and you’ll see this white page with authorization code. If you’re running Pi Node, you are probably familiar with this process. Open your mobile app and tap on the Authorize sandbox link at the bottom of Pi Utilities page. And you need to type the authorization code and press confirm. When your sandbox environment is authorized, you’ll see your app within the sandbox environment, which is the page you saw earlier.

Now open the devtool of the browser. There’s a small context selector here. You can select localhost to get your app’s context. After you select localhost, if you type Pi in the console, you can access it. Of course, you’ll see some value to be null because the current user is not authenticated yet.

Now that we can run our app in the sandbox, let’s take a look at the SDK shortly. The very first function you’ll encounter is the authenticate function. It takes an array of strings called scopes, and one callback function called onIncompletePaymentFound.

There are two available scopes, which are username and payments. For now, the scopes feature is still a work in progress. What that means is the authenticate function will consider both scopes as requested for now. Nonetheless, you should implement your app with only relevant scopes. Check our SDK reference hosted on our github repository for future updates.

onIncompletePaymentFound function handles an incomplete payment between your app and this user you’re authenticating. A payment is considered incomplete when you don’t submit the server-side completion API call. In this demo app, we are proposing an example usage, where the payment is sent to the app server to find the previous order and mark it as paid. More details about payment is available in the Payment video. For now, let’s just keep in mind that we need to pass a callback function that handles the incomplete payment from the server side.

The authenticate function will return a promise, which looks something like this. The return value might change later, but what’s important is that you need to make sure to send it to the app server and store this information in your database. It’s also important to verify this by hitting /me endpoint from your server, because malicious users can pretend they are someone else. You can find more about the /me endpoint on our Pi-Platform-documentation.

So in this video, we have seen how to use SDK, run your app in the sandbox and authenticate the current user. In the next video, I’m going to cover how to process payments, which are wrappers around the blockchain transaction between your app and users. Thanks for watching.

Hackathon Workshop video 3

Title: Pi Payments introduction

Video Script:

Welcome back everyone. In the previous video, we saw how to use the Pi SDK, run your app in the sandbox and authenticate the user. In this video, I’m going to walk you through the overall payment process. The process I’m about to explain is at a very high level, but even with this, you’ll be able to understand what you need to do to create a payment. If you want to learn more about what’s actually happening behind the scene, please refer to our Pi Platform Documentation. Now let’s begin.

Throughout the process, essentially 4 parties are involved. Your app, Your App Server, the Pi Servers and the Pi Blockchain. The most important point to remember is that all of them must be completely synchronized about the state of a payment to avoid any possible race conditions. If something goes wrong, a user may pay for an item that’s already given to someone else, or a user may pay for an item twice because the process gets interrupted. To avoid such cases, the Pi Core Team has implemented a protocol as a part of the Pi SDK and you don’t need to worry at all.

With the Pi SDK, creating a payment in Pi Apps is very simple. Let’s have a look at the createPayment function. It takes 2 arguments, which are paymentData object and an object of callback functions. The paymentData object is comprised of three items. Amount to be paid, memo for users, and metadata for your own usage. If any of these are missing, you’ll get an error.

onReadyForServerApproval is a function that gets called when the payment id is ready. Using this function, you need to pass payment id and other relevant data to your app server. Then on your server, you should reserve an item for the user who’s about to buy it, and let Pi server know that you’re ready to proceed. In other words, you need to make sure that your server is aware of the current payment through this function.

onReadyForServerCompletion is a function that gets called after the blockchain transaction has been submitted to the Pi blockchain. Your job is again to pass any relevant data to your app server. On your server, you can verify the payment and deliver the item that was reserved for the user. In the end, you should complete the payment by letting the Pi server know that you have received the payment and delivered the item. The other 2 functions are onCancel and onError functions. As their names suggest, they are functions that will be invoked when the payment gets canceled and when an error occurs.

Let’s not forget about the onIncompletePaymentFound function that we saw in the previous video. To remind you, this function is in charge of completing any incomplete payment. You might be wondering why you need to implement this function. There’s a chance that a payment process gets interrupted unexpectedly. A user might lose the internet connection, the app might crash or the server might not respond. If the payment process fails before a user pays, then it’s fine. The user just needs to start the process again. Of course, you need to clean up the stale orders on your server. But what if the user already paid and all of a sudden the process ends without being completed gracefully? That’s where this function comes in and plays the role. The Pi SDK will detect such payment when the user is authenticated and when a user tries to make a new payment, and if it finds an incomplete payment, it will request your app to complete the payment. Okay, so we are going to implement the functions in a minute. But there’s one more step you can’t forget, which is obtaining the API Key.

Assuming that you have registered your app on the developer portal, let’s generate the API Key, if you haven’t done yet. Select your app at the bottom, and if you tap on the “get api key” button, you can create a new key. Save the key before you close the window. Using this key, you can hit our endpoints and update the status of the Payment.

We are back to our demo app, and now we are going to implement the callback functions. For the sake of time, I have prepared the code snippet. Let’s fill this in together. We now all know what this is. What you want to do here is to call your server to hit our endpoint from your server. Keep in mind that this slash approve is just an arbitrary route I’m using as an example. Again, to complete the payment, you need to call your server to hit our endpoint. The last two functions are for your own usage. When the payment is canceled, mark it as cancelled on your server as well. Also handle the error however you want.

Now let’s complete the backend. In this demo, I’m running the node server, but you can choose any backend you prefer. Also keep in mind that the actual implementation is up to you. I’m just demonstrating a rough example to help you understand the process. First, let’s see the approve route. When the payment is created, you need to reserve an item for the user, and map the paymentId to the current order. Then make sure to hit approve endpoint to approve the payment. The same thing goes for the complete route as well. You can verify the payment if you want, deliver the item to the user, mark the order as paid and complete the payment by hitting complete endpoint. We shouldn’t forget the incomplete route. Process the incomplete payment, and hit the complete endpoint. Although I’m skipping here, don’t forget to handle the cancel route as well. We are finally ready to create a payment.

Now that the code is ready, let’s see the flow from the beginning. As soon as I tap on the button, the payment flow begins. I can see the next page only if the payment is approved from the app server. Then I can review the details and if I think it’s correct, I’ll use my passphrase to sign and submit the transaction to the Pi blockchain. Now the transaction is submitted, and we are waiting for the app server to complete the payment flow. When the app server finally completes the payment, I can see this result, and this is the end of the demo. Thanks for watching.