|
1 | | -Content upcoming soon... |
| 1 | +# IFTTT.NET: Simplifying IFTTT integration for .NET Developers |
| 2 | + |
| 3 | +**IFTTT.NET** is a powerful .NET library designed to streamline your interaction with the **[IFTTT](https://ifttt.com/explore)** platform. Whether you're building web applications, services, or IoT solutions, our toolkit empowers you to seamlessly integrate IFTTT into your projects. |
| 4 | + |
| 5 | +## Why Use IFTTT.NET? |
| 6 | + |
| 7 | +- **Boilerplate-Free**: Say goodbye to repetitive code! Our library abstracts away the complexities of IFTTT integration, allowing you to focus on what matters most. |
| 8 | +- **Minimal Effort**: Get started quickly. IFTTT.NET simplifies the process of setting up triggers, actions, and applets. |
| 9 | +- **Modern API**: We've designed IFTTT.NET to be intuitive and easy to use. |
| 10 | + |
| 11 | +## Getting Started |
| 12 | + |
| 13 | +> **TL;DR**\ |
| 14 | +> Go to the [Samples](https://github.com/Invvard/InvvardDev.IFTTT.NET/tree/main/samples) folder and check out the sample projects. |
| 15 | +
|
| 16 | +### Setup an IFTTT Trigger |
| 17 | + |
| 18 | +1. **Install package**: Add our NuGet package [InvvardDev.Ifttt](https://www.nuget.org/packages/InvvardDev.Ifttt) to your project. |
| 19 | +2. **Create a Trigger class**: add a class implementing the `ITrigger` interface with the TriggerAttribute on top. This will allow IFTTT.NET to find, recognize and handle your Trigger: |
| 20 | + |
| 21 | + ```csharp |
| 22 | + [Trigger("trigger_slug")] |
| 23 | + public class YourNewTrigger : ITrigger |
| 24 | + { |
| 25 | + [DataField("trigger_field_slug")] |
| 26 | + public string YourTriggerFieldName { get; init; } = default!; |
| 27 | + |
| 28 | + public Task ExecuteAsync(TriggerRequest triggerRequest, CancellationToken cancellationToken = default) |
| 29 | + { |
| 30 | + // Your trigger logic goes here |
| 31 | + |
| 32 | + return Task.CompletedTask; |
| 33 | + } |
| 34 | + } |
| 35 | + ``` |
| 36 | + |
| 37 | + The `TriggerAttribute` is used to define the Trigger slug. The `DataFieldAttribute` is used to define the Trigger field slug.\ |
| 38 | + The `ExecuteAsync` method is the entry point for your Trigger logic. It will be called by IFTTT.NET when the Trigger is activated. |
| 39 | +3. **Add the test setup**: one of the mandatory step for publishing an IFTTT service is to have a test setup endpoint.\ |
| 40 | + Just add a class implementing the `ITestSetup` interface. |
| 41 | + |
| 42 | + ```csharp |
| 43 | + public class TestSetup : ITestSetup |
| 44 | + { |
| 45 | + public Task<ProcessorPayload> PrepareSetupListing() |
| 46 | + { |
| 47 | + var processors = new ProcessorPayload { Triggers = new Processors() }; |
| 48 | + |
| 49 | + processors.Triggers |
| 50 | + .AddProcessor("trigger_slug") |
| 51 | + .AddDataField("trigger_slug", "trigger_field_slug", "some_value"); |
| 52 | + |
| 53 | + return Task.FromResult(processors); |
| 54 | + } |
| 55 | + } |
| 56 | + ``` |
| 57 | + |
| 58 | + The `PrepareSetupListing` method is used to define the test setup payload. It will be called by IFTTT.NET when the test setup endpoint is called.\ |
| 59 | + You can find the complete list of required Triggers, actions and queries in your service dashboard, under the `API` tab, `Endpoint tests` section, `Test setup` tab and click on either "**View** or **Download** a scaffold JSON response for your service". |
| 60 | + |
| 61 | +4. **Configure startup**: In your application startup logic, configure the IFTTT.NET client: |
| 62 | + |
| 63 | + ```csharp |
| 64 | + var builder = WebApplication.CreateBuilder(args); |
| 65 | + |
| 66 | + builder.Services |
| 67 | + .AddIftttToolkit("<your-service-key>") |
| 68 | + .AddTestSetupService<TestSetup>() |
| 69 | + .AddTriggerAutoMapper() |
| 70 | + .AddTriggers(); |
| 71 | + |
| 72 | + var app = builder.Build(); |
| 73 | + |
| 74 | + app.ConfigureIftttToolkit() |
| 75 | + .UseServiceKeyAuthentication() |
| 76 | + .ConfigureTriggers(); |
| 77 | + |
| 78 | + app.Run(); |
| 79 | + ``` |
| 80 | + |
| 81 | +5. **Run your application**: That's it! Your Trigger is now ready to be used in IFTTT Applets. |
| 82 | + |
| 83 | +### Swagger support |
| 84 | + |
| 85 | +Swagger is a good way to test your Triggers and Actions. Just add the `AddSwaggerGen` and `UseSwagger` methods to your application startup logic (see step 4). |
| 86 | + |
| 87 | +```csharp |
| 88 | +builder.Services.AddSwaggerGen(); |
| 89 | +[...] |
| 90 | +app.UseSwagger().UseSwaggerUI(); |
| 91 | +``` |
| 92 | + |
| 93 | +In the event that you want to run Swagger with the Service Key Authentication activated, configure SwaggerGen like this: |
| 94 | + |
| 95 | +```csharp |
| 96 | +builder.Services.AddSwaggerGen(options => options.AddIftttServiceKeyScheme()); |
| 97 | +``` |
| 98 | + |
| 99 | +It will add a new security scheme to the Swagger UI, allowing you to test your Triggers and actions with the Service Key Authentication. |
| 100 | + |
| 101 | +## Real time notifications |
| 102 | + |
| 103 | +Next, you can use the real time notification feature to make your Trigger more responsive.\ |
| 104 | +When you have a new data to send to IFTTT, prepare your Trigger identities or User IDs and call `ITriggerHook.SendNotification`.\ |
| 105 | +Here is an example of a controller sending a notification to IFTTT with Trigger identities: |
| 106 | + |
| 107 | +```csharp |
| 108 | +[ApiController] |
| 109 | +[Route("api/[controller]")] |
| 110 | +public class RealTimeNotificationController(ITriggerHook realTimeHook) : ControllerBase |
| 111 | +{ |
| 112 | + [HttpPost] |
| 113 | + public async Task NotifyAsync(CancellationToken cancellationToken = default) |
| 114 | + { |
| 115 | + var notificationRequest = new List<RealTimeNotificationModel> |
| 116 | + { |
| 117 | + RealTimeNotificationModel.CreateTriggerIdentity("trigger_identity_12345"), |
| 118 | + RealTimeNotificationModel.CreateTriggerIdentity("trigger_identity_67890"), |
| 119 | + }; |
| 120 | + |
| 121 | + await realTimeHook.SendNotification(notificationRequest, cancellationToken); |
| 122 | + } |
| 123 | +} |
| 124 | +``` |
| 125 | + |
| 126 | +If you use User IDs, just call `RealTimeNotificationModel.CreateUserId("<user_id>")` instead of `RealTimeNotificationModel.CreateTriggerIdentity("<trigger_identity>")`. |
| 127 | + |
| 128 | +## Roadmap |
| 129 | + |
| 130 | +As of today, the library is still in its early stages and only supports Triggers, basic Data field and Service Key Authentication. We are working on adding support for Data field validation, User Authenticated integration and other advanced features .\ |
| 131 | +Fortunately, IFTTT is designed in such a way that once Triggers are implemented, Actions and Queries should be easy to implement. |
| 132 | + |
| 133 | +## Contributing |
| 134 | + |
| 135 | +Check the [contributing introduction](./CONTRIBUTING.md). |
| 136 | + |
| 137 | +## Glossary |
| 138 | + |
| 139 | +As IFTTT is designed in a way that Trigger, Action and Query have a common structure.\ |
| 140 | +So in order to be as generic as possible, here are some definitions of the terms used in the library: |
| 141 | + |
| 142 | +- **Processor**: refers to a Trigger, an Action or a Query. |
| 143 | +- **Data field**: a field that is used to pass data to or from a Trigger, an Action or a Query. |
0 commit comments