SparkSetup 0.7.0

SparkSetup 0.7.0

×

测试测试✗
Lang语言 Obj-CObjective C
许可证 Apache 2
发布最后发布2017年3月

由Ido Kleinman 维护。

SparkSetup 0.7.0

Particle 设备安装库（beta）

Particle 设备安装库旨在将Particle设备在您的应用中的初始设置过程集成。这个库可以使您轻松调用一个独立的设置向导UI，用于设置由Particle设备（Photon、P0、P1）供电的互联网连接产品。可以通过一个定制代理类轻松自定义设置UI，包括外观和感觉、颜色、文本和字体，以及定制的品牌标志和定制的产品教学视频。如果没有设置这些属性，则已经有很好的默认设置，但是您可以按照需要覆盖外观和感觉来适应其余的应用。

Photon的无线设置过程使用与Core非常不同的底层技术。当Core使用TI SmartConfig时，Photon使用我们称之为“软AP”的技术——也就是说，Photon公告一个Wi-Fi网络，您从移动应用加入该网络以交换凭证，然后Photon使用您提供的Wi-Fi凭证进行连接。

使用设备设置库，您从应用中中进行一个简单的调用，例如当用户点击“设置我的设备”按钮时，然后一系列屏幕引导用户完成设置过程。当过程完成后，应用用户会回到她点击“设置我的设备”按钮的屏幕，并且您的代码已经传递了她刚刚设置并声明的设备实例。iOS 设备设置库实现为一个开源的 Cocoapod 静态库，也可以作为 Carthage 动态框架依赖项。有关更多信息，请参阅安装部分。它适用于包含任何类型依赖项的 Objective-C 和Swift 项目。

重新品牌声明

Spark 最近已重新命名为 Particle。代码中当前包含 SparkSetup 关键字作为类的前缀。这很快将被替换为 ParticleDeviceSetup。

使用方法

Cocoapods

在您的视图控制器实现文件中导入 SparkSetup.h，对于 Swift 项目使用桥接头（有关详细信息，请参阅安装部分）。

Carthage

在 Objective-C 文件中，使用 #import <ParticleDeviceSetupLibrary/ParticleDeviceSetupLibrary.h>，在 Swift 文件中使用 import ParticleDeviceSetupLibrary。

然后通过以下方式调用设备设置向导

Objective-C

SparkSetupMainController *setupController = [[SparkSetupMainController alloc] init];
setupController.delegate = self; // why? see "Advanced" section below 
[self presentViewController:setupController animated:YES completion:nil];

Swift

if let setupController = SparkSetupMainController()
{
    setupController.delegate = self
    self.presentViewController(setupController, animated: true, completion: nil)
}

或者，如果您的应用需要将 Particle 云认证过程和设备设置过程分开，您可以调用

Objective-C

SparkSetupMainController *setupController = [[SparkSetupMainController alloc] initWithAuthenticationOnly:YES];
[self presentViewController:setupController animated:YES completion:nil];

Swift

if let setupController = SparkSetupMainController(authenticationOnly: true)
{
    self.presentViewController(setupController, animated: true, completion: nil)
}

此操作将在用户成功登录或注册后才调用Particle Cloud身份验证（登录/注册/密码恢复界面），控制权将返回到调用应用。如果已存在活跃用户会话，则将立即返回控制权。

未申领设备配置Wi-Fi凭据

如果您的应用需要让用户在不变更其所有权的情况下配置设备Wi-Fi凭据，您也可以通过initWithSetupOnly实现，并允许用户跳过身份验证（请在自定义部分中查看allowSkipAuthentication标志）。如果存在活跃用户会话，则会使用它并申领设备；否则不会。因此，在没有活跃用户会话的情况下调用设置将执行配置设备Wi-Fi凭据所需的设置步骤，但不会对其进行申领。然而，使用活跃用户会话调用-initWithSetupOnly:方法本质上是与调用-init:相同的。用法

Objective-C

SparkSetupMainController *setupController = [[SparkSetupMainController alloc] initWithSetupOnly:YES];
[self presentViewController:setupController animated:YES completion:nil];

Swift

if let setupController = SparkSetupMainController(setupOnly: true)
{
    self.presentViewController(setupController, animated: true, completion: nil)
}

密码管理扩展支持

从库版本0.6.0开始，1Password管理器扩展支持已添加到注册和登录界面——开发者无需采取任何行动。如果iOS设备上安装了1Password，则锁定图标将出现在密码字段中，允许用户填写其保存的密码（登录）或创建一个新密码（注册）。唯一的建议是在您的应用项目中的info.plist文件中添加LSApplicationQueriesSchemes = org-appextension-feature-password-management键值对。

有关更多信息，请在此处查看。

自定义

通过访问单例外观代理SparkSetupCustomization，自定义设置的外观和感觉[SparkSetupCustomization sharedInstance]并修改其默认属性。设置此类中的属性是可选的。为了方便，这些属性采用Objective-C语法展示，但与Swift项目的工作方式相同——使用String和Bool代替NSString和BOOL。

产品/品牌信息

 NSString *deviceName;                  // Device/product name 
 UIImage *productImage;                 // Custom product image to display in "Get ready" screen *new*
 NSString *brandName;                   // Your brand name
 UIImage *brandImage;                   // Your brand logo to fit in header of setup wizard screens
 UIColor *brandImageBackgroundColor;    // brand logo background color
 NSString *instructionalVideoFilename;  // Instructional video shown landscape full screen mode when "Show me how" button pressed on second setup screen

技术数据

 NSString *modeButtonName;              // The mode button name on your product
 NSString *listenModeLEDColorName;      // The color of the LED when product is in listen mode
 NSString *networkNamePrefix;           // The SSID prefix of the Soft AP Wi-Fi network of your product while in listen mode

法务/技术信息链接

 NSURL *termsOfServiceLinkURL;      // URL for terms of service of the app/device usage
 NSURL *privacyPolicyLinkURL;       // URL for privacy policy of the app/device usage

外观和感觉

 UIColor *pageBackgroundColor;     // setup screens background color
 UIImage *pageBackgroundImage;     // optional background image for setup screens
 UIColor *normalTextColor;         // normal text color
 UIColor *linkTextColor;           // link text color (will be underlined)
 UIColor *elementBackgroundColor;  // Buttons/spinners background color
 UIColor *elementTextColor;        // Buttons text color
 NSString *normalTextFontName;     // Customize setup font - include OTF/TTF file in project
 NSString *boldTextFontName;       // Customize setup font - include OTF/TTF file in project
 CGFloat fontSizeOffset;           // Set offset of font size so small/big fonts can be fine-adjusted
 BOOL tintSetupImages;             // This will tint the checkmark/warning/wifi symbols in the setup process to match text color (useful for dark backgrounds)
 BOOL lightStatusAndNavBar;        // Make navigation and status bar appear in white or black color characters to contrast the selected brandImage color // *New since v0.6.1*

产品创建者

如果您正在为您的产品开发应用程序/您是产品创建者，您应将productMode设置为YES（或Swift中的true）——这将启用产品模式，该模式使用不同的API端点，以便添加/设置分配给您的产品的设备。

如果将productMode设置为YES / true，请确保还要提供productId（以及productName）——请在此处了解如何找到productId编号。

请确保向SparkCloud类注入用于创建客户的范围OAuth凭据，以便应用用户可以创建账户。在此处了解如何正确操作。

 BOOL productMode;              // enable product mode
 NSString *productName;         // product display name 
 NSUInteger productId;            // Product Id number from Particle console

跳过身份验证

 BOOL allowSkipAuthentication;          // Allow user to skip authentication (skip button will appear on signup and login screens)
 NSString *skipAuthenticationMessage;   // Message to display to user when she's requesting to skip authentication (Yes/No question)

高级

当设置向导成功完成后，您可以通过使您的视图控制器符合协议 <SparkSetupMainControllerDelegate> 来获取已设置的设备 - SparkDevice 的激活实例。

Objective-C

-(void)sparkSetupViewController:(SparkSetupMainController *)controller didFinishWithResult:(SparkSetupMainControllerResult)result device:(SparkDevice *)device;

Swift

func sparkSetupViewController(controller: SparkSetupMainController!, didFinishWithResult result: SparkSetupMainControllerResult, device: SparkDevice!)

如果 (result == SparkSetupMainControllerResultSuccess) 或（在 Swift 中简写为 (result == .Success)），则会调用此方法，此时设备参数将包含一个活跃的 SparkDevice 实例，您可以使用 iOS Cloud SDK 与其交互。如果设置失败、被取消或被中断，您可以通过查看枚举值 SparkSetupMainControllerResult 的文档来确定确切的原因。更多信息请见此处。

如果设置失败，并且您仍然可以通过符合 @optional 代理函数来确定最后一次尝试设置的设备 ID：(自 0.5.0 以来新增)

Objective-C

- (void)sparkSetupViewController:(SparkSetupMainController *)controller didNotSucceeedWithDeviceID:(NSString *)deviceID;

Swift

func sparkSetupViewController(controller: SparkSetupMainController!, didNotSucceeedWithDeviceID deviceID: String)

示例

Swift 的 Cocoapods 使用示例应用程序（在 此处 可找到）。示例应用程序演示了 - 调用设置向导、自定义其 UI 并在设置向导完成后使用返回的 SparkDevice 实例（代理）。请随意通过提交拉取请求对该示例进行贡献。

参考

请在 Cocoadaocs 网站上查看参考资料，或者在 SparkSetupCustomization.h 和 SparkSetupMainController.h 中的每个公共方法或属性中查看 javadoc 风格的注释。如果您的 XCode 项目中 Device Setup 库安装成功，那么您应该能够按下 Esc 来从 XCode 获取每个公共方法或属性的自动完成提示。

要求 / 限制

  • 支持 iOS 8.0 及以上版本
  • 当前设置向导仅显示在横屏模式。
  • 需要 XCode 7 及以上版本

安装

对 Swift 项目的支持

要从 Swift 基于的项目中使用 Particle Device Setup 库 - 您需要配置一个桥接头 - 请阅读此处，作为额外资源，您可以查阅关于此问题的官方Apple 文档。

通信

  • 如果您 需要帮助，请使用 我们的社区网站
  • 如果您 发现了一个错误，并且可以提供可靠复现步骤，请打开一个问题。
  • 如果您 有功能请求，请打开一个问题。
  • 如果您 想要贡献，请提交拉取请求。

许可

Particle Device Setup 库在 Apache 2.0 许可下可用。有关更多信息，请参阅 LICENSE 文件。

维护者